@comchatx/cx-sponsored-ads-playbook 0.0.0-stage → 0.1.1

package/skills/ads-review/references/decomposition.md

@@ -0,0 +1,27 @@
+# Decomposition: the metric chain, benchmarks and change methods
+
+## The chain
+
+- Amazon defines click-through rate as clicks over impressions and cost per click as cost over clicks, so on a cost-per-click row spend equals impressions × CTR × CPC (A7).
+- Optmyzr describes the metrics as a chain from impressions through CTR, clicks, conversion rate and orders to sales and ACoS, and names three root causes of an ACoS rise: traffic, conversion rate, and demand or market shift (A7).
+- Optmyzr calls a conversion-rate drop "the most misdiagnosed cause of ACoS spikes" (A7).
+- Chuck Kessler (Canopy) orders a conversion drop's causes from the Featured Offer first, and Bob Norberg (eComEngine) puts availability first and ads last (A7).
+- What each metric counts: references/metrics.md.
+
+## Benchmarks
+
+- Amazon's benchmark metrics give the 25th, 50th and 75th percentiles of unnamed peer brands in a category (A20).
+- Third-party quarterly benchmarks, Tinuiti's as summarized by Karooya, report spend and CPC moves across their clients (A20).
+
+## Splitting a change
+
+- The log-mean Divisia index splits the change in a product of factors exactly into one term per factor (A21).
+- An aggregated rate can show a pattern none of its units shows, which is Simpson's paradox (A21).
+- Root-cause methods exist for advertising revenue and derived measures, Adtributor among them (A22).
+- Given an analyst-supplied causal graph, the methods of Budhathoki et al., Amazon researchers, attribute a distribution change or an outlier to its mechanisms, and DoWhy's `gcm` module implements them (A22).
+
+## Telling a shift from noise
+
+- For Poisson counts the k-sigma limits are c ± k√c, and when an indicator varies more than chance alone, ignoring the over-dispersion classifies too many units as abnormal (A23).
+- CUSUM charts detect sustained mean shifts of 2 sigma or less more efficiently than Shewhart charts, and EWMA charts weight past data so a small or gradual drift can be detected (A23).
+- PELT finds changepoints in time linear in the series length (A23).

package/skills/ads-review/references/metrics.md

@@ -0,0 +1,65 @@
+# Metrics: attribution, definitions, traffic quality and settling
+
+## Attribution
+
+- Sponsored ads report a conversion on the date of the ad interaction, the traffic date, which may differ from the conversion date (M1).
+- Legacy Sponsored Brands and Display, Video and Audio campaigns reported on the conversion date before unified reporting and now report on the traffic date, which moves conversions earlier without changing their total (M1).
+- Amazon attributes each conversion to at most one ad interaction across all campaigns and all advertisers, ranked promoted-product clicks, brand-halo clicks, promoted-product views, brand-halo views, then last touch with the last click before the last view (M2).
+- Amazon states that Sponsored Products for sellers is merchant-based and does not normally compete for attribution with brands, except that where the same advertiser wins as both merchant and brand, the more relevant ad is chosen; the page does not say whether "the same advertiser" is the advertising account, the global account or the brand (M25).
+- Lookback and credited products differ by ad product and advertiser: SP for sellers is 7 days on clicks, crediting the advertised product and anything else the merchant sells (M3).
+- SP for vendors and authors is 14 days on clicks, crediting the advertised and same-brand products sold by Amazon; SB, display, Streaming TV and DSP are 14 days and credit the brand halo (M3).
+- Unified reporting and v1 drop window suffixes, so an SP base metric is 7-day for sellers and 14-day for vendors, and other campaign types are 14-day (M3).
+- Ad Badger's description of SP and SB as 14-day click attribution, with reports built by order date, contradicts Amazon's attribution page (M3).
+- SP and CPC Sponsored Brands attribute to clicks only; vCPM Sponsored Brands, display, Streaming TV and DSP also credit views meeting the MRC standard (M4).
+- From 2026-01-01 vCPM SB and display use a shopping-signal enhanced view model with a shorter window, keeping the old 14-day model as "all views" metrics, and Amazon publishes no incrementality figure for the new model (M4).
+- KENP read is attributed to reading up to 14 days after an ad click and reported on the day the pages were read (M12).
+- Amazon's multi-touch attribution, announced at unBoxed 2024 as a beta for US advertisers, splits credit across ad touches in proportion to their value and is published as Reporting v1's `metric.multiTouch*` fields beside last-touch ones, each requiring its last-touch counterpart; the field list is v1's *Purchases (Amazon retail conversions)* page, https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/metrics/amazon-retail-conversions/purchases (M16).
+- Amazon's launch page places it in "most report types for version 3", but the v3 column pages show no multi-touch column and every v1 multi-touch field gives its v3 name as "N/A" (M16).
+- Lily Tong, a director of measurement at Amazon Ads, quoted by Digiday, said roughly 20% of a brand's sales value shows up after the attribution window, from an Amazon analysis of more than 2 million campaigns in June across all ad products, not split out for Sponsored Products (M19).
+- Digiday reports agencies split on long-term sales, some treating it as "a forecast that shifts whenever the campaign mix changes" (M19).
+
+## Definitions
+
+- CTR is clicks ÷ impressions, CPC cost ÷ clicks, CPM cost ÷ impressions × 1,000, and vCPM cost ÷ viewable impressions × 1,000 (M6).
+- Unified reporting and v1 have no ACOS field, while v3 has `acosClicks7d` and `acosClicks14d` on targeting, search-term, advertised-product and ad-extension types but not `spCampaigns` (M6).
+- In unified reporting and v1 "purchase rate" (`metric.purchaseRate`) is purchases ÷ impressions, and the per-click rate is "purchase rate over clicks" (`metric.purchaseRateOverClicks`, v3 "14 Day Conversion Rate") (M7).
+- Amazon's Sponsored Products search-term help page, modified 2026-05-18, still calls the per-click rate "Purchase rate" (M7).
+- Reporting v3 carries SP 1-, 7-, 14- and 30-day click-attributed purchases, sales and units with same-SKU and other-SKU variants; v1 has no day-count variant (M8).
+- Sponsored Brands `purchases` and `sales` count 14 days after a click or a view, and `sales14d` includes view-attributed sales for vCPM campaigns (M8).
+- A purchase is an order event that can hold several units (M9).
+- Attributed sales exclude tax and cart discounts, can include items sold by Amazon or other sellers and used items, and lose payment failures and cancellations within 72 hours, deducted over up to 7 days (M9).
+- Amazon reports no impressions, clicks or other traffic at the converted-product level, because one interaction can lead to several products (M10).
+- Detail page views, add to cart, viewable impressions and vCPM are not offered for SP in v1; detail page views are not unique per customer and include halo in unified reporting (M11).
+- Unified reporting renames metrics and widens some definitions (M17).
+- The console's legacy report centres shut on 2026-12-31, with saved reports, schedules and history deleted, and new legacy reports and edits stop on 2026-12-17; Amazon says these dates are subject to change (M17).
+
+## Traffic quality
+
+- Impressions and clicks are net of invalid traffic, with gross and invalid counts reported separately (M5).
+- Amazon filters before the bid and after the impression, monitors for up to 30 days, bills net of what it finds, and can change console cost for 72 hours (M5).
+- Amazon names a fall in invalid-traffic rate with a rise in CTR or clicks and a fall in CVR as a signal of undetected invalid traffic, while an IVR level alone is not one (M5).
+- The MRC accreditation renewed on 2026-07-08 covers Sponsored Products gross clicks and clicks net of SIVT on Amazon placements, in total only (M15).
+- Impressions and conversions are not accredited, and Sponsored Brands and Sponsored Display are not on the MRC list (M15).
+
+## Days, zones and currencies
+
+- v1 aggregates days in each campaign's time zone (`timeZone.value`) and money in the campaign budget currency, needing `budgetCurrency.value` with money metrics and `convertedCurrency.value` for converted figures (M13).
+- v2 and v3 reports use the profile's time zone, change history timestamps are UTC, and console downloads use the account's registered zone (M13).
+
+## Settling
+
+- Amazon's settling schedule: data within about 12 hours, impressions and clicks changing for up to three days, and conversions first within 24 hours and restated at 1, 7 and 28 days, up to 42 days for a 14-day window (M14).
+- Another Amazon page says "subject to change for up to 60 days", and Stream v2 has a 70-day window (M14).
+- Amazon advises waiting at least five days for accurate clicks, and the console's sales take up to 48 hours (M14).
+- No report marks a day final, and Amazon's P99 target from impression to availability is 12 hours (M14).
+- Optmyzr pulled 14,991 campaigns' 14-day figures daily over 17 days and found attributed sales in the top 5% growing at least 18.75% after the first read (M20).
+
+## Measurement standards and research
+
+- The IAB/MRC Retail Media Measurement Guidelines (January 2024) require attribution windows that are empirically supported and disclosed before the campaign, encourage day-level lag data, require viewable impressions for attributing outcomes to exposure, a click being able to stand in, require a disclosed basis for 12-month forecasts, and highly recommend RCTs for incrementality (M22).
+- Amazon's attribution page says viewability is inferred from historical data and placement characteristics where it is not measured directly (M22).
+- The IAB and IAB Europe guidelines of November 2025 grade new-to-brand percentage, platform-reported incrementality and simple multi-touch attribution as "Weak" causal evidence and experiments as "Strong" (M22).
+- A surrogate index of short-term outcomes recovers a long-term effect only under the surrogacy assumption that the long-term outcome is independent of treatment given the surrogates (M21).
+- Attribution research finds last-click credit differs substantially from model-based credit, attribution weights follow exposure counts where profitable allocation does not, and game-theoretic credit is variable importance unless causal assumptions hold (M23).
+- The same research finds single-campaign effects measured by holdout imprecise and 78% of a display campaign's purchase lift coming from people who never clicked, and describes ghost ads, which compare the exposed with their randomized would-have-been-exposed counterparts (M23).
+- Persistence modelling separates temporary from permanent effects, and Qin found every Amazon brand KPI she studied stationary, so no marketing effect lasted forever (M24).

package/skills/ads-review/references/reads.md

@@ -0,0 +1,30 @@
+# Reads: hosts, profiles, accounts and the offer behind an ad
+
+## Hosts, tokens and permissions
+
+- Origins, headers, the token trade and the refresh token's expiry: the amazon-ads skill's references/door.md.
+- The Ads API's three regional hosts, NA, EU and FE, each have their own marketplace list; Ireland is a country code that the Profiles model tables under region EU, while Amazon's endpoint tables omit it (A1).
+- Login with Amazon tokens are valid in every region, and an access token lives 60 minutes (A2).
+- The `advertising::campaign_management` scope lets an application act with whatever advertising permissions the authorising user holds; each operation names the permissions it requires, and too little permission answers 401 (A3).
+
+## Profiles and global accounts
+
+- A profile is one advertiser account in one marketplace; the profile list returns nothing for an account that has never created a campaign, and types each profile as `seller`, `vendor` or `agency`, with `KDP_AUTHOR` as a sub-type (A4).
+- The United Kingdom is `UK` in the Profiles model and `GB` in the v1 `Marketplace` and `CountryCode` enums (A6).
+- Ads API v1 reporting, v1 recommendations and Stream v2 identify the advertiser by a global account id (`amzn1.ads-account.g.*`), not by profile (A5).
+- v1's advertiser-account query maps each global account to its per-marketplace `profileId`s, paging by `nextToken`, with pages that can be empty while a `nextToken` remains (A5).
+- Amazon names it the replacement for the legacy `adsAccounts` operations, which answer `Warning: 299` from July 2026, block new client integrations (existing callers continue "through an allowlist") and answer `404` from July 2027 (A5).
+- Stream v2 takes no manager account id, Vendor Group id or Seller Central merchant id (A5).
+
+## The offer behind an ad
+
+- Amazon states that an offer whose price plus shipping is above the Competitive External Price, where one exists, or above recent prices is ineligible to be the Featured Offer at that price "regardless of changes to price or stock of competitors" (A11).
+- SP-API exposes the reference prices (`PRICING_HEALTH`), the price at or below which an offer can expect to win, which Amazon says "is not guaranteed" (`getFeaturedOfferExpectedPriceBatch`, up to 40 SKUs), and the winner per customer segment (`getCompetitiveSummary`) (A11).
+- Landed price subtracts Amazon Points, and the marketplaces where the Points program runs are stated in Amazon's Product Fees model, *productFeesV0.json*, https://github.com/amzn/selling-partner-api-models/blob/main/models/product-fees-api-model/productFeesV0.json (A11).
+- Repricer.com and AMALYZE hold that price moves Featured Offer status and conversion, without publishing data or a method (A11).
+- The Buy Box holder over time is in Keepa's histories, `-1` when no offer or seller qualified, and the current holder in SP-API `getItemOffers` as `IsBuyBoxWinner` (A12).
+- Sales and Traffic's `buyBoxPercentage` is the share of page views with a buy box, and that report's `refundRate` description reads inverted (A12).
+- A listing can be hidden from search by the Listings Items enforcement action `SEARCH_SUPPRESSED`, and Catalog Items returns variation relationships (A13).
+- Between 2026-02-12 and 2026-05-31, by category, Amazon stopped sharing reviews between variations "with significant differences", which Amazon says may affect a product's overall star ratings and review counts (A13).
+- PPC Land's Luis Rijo states that the star rating under a sponsored product comes from the same shared or non-shared review pool, so a variation that loses shared reviews shows a lower rating in its ad unit (A13).
+- SP-API notifications (`ANY_OFFER_CHANGED`, `PRICING_HEALTH`, `FBA_INVENTORY_AVAILABILITY_CHANGES`, listing issues) need an SQS or EventBridge destination; the same facts can be polled from documented reads (A14).

package/skills/ads-review/references/reports.md

@@ -0,0 +1,71 @@
+# Reports: types, windows, limits, the v3 sunset and Stream
+
+- How a report, v3 or v1, is asked for, addressed, polled and landed: the amazon-ads skill's references/door.md.
+
+## The sunset
+
+- Reporting v3, Sponsored Ads v2 reporting and Marketing Stream v1 stop delivering data on 2027-06-30; Reporting v1 and Stream v2 have been generally available since 2026-09-30 (R1).
+
+## Reporting v3
+
+- A pending v3 report can be cancelled; a completed one carries a pre-signed S3 `url` expiring at `urlExpiresAt`, 3600 seconds by default, which Amazon says "may vary", and a failed one carries a `failureReason` (R2).
+- For a create identical to a report still processing, which answers `425`, Amazon's direction is to wait for the existing report and keep report ids (R3).
+- v3 report types are per ad product, each with its own `groupBy`, filters, maximum range and retention, and a filter applies only when every `groupBy` supports it (R5).
+- SP has campaign, targeting, search term, advertised product, purchased product, gross and invalid, prompt and video extension types, with ad-group and placement data from `spCampaigns` grouped by `adGroup` or `campaignPlacement` (R5).
+- SB adds ad, ad group and placement types; SD has ad group but no search term (R5).
+- Audience boosts have `spAudiences` and `sbAudiences`, 31 days per request and 95 days kept, though the v3 columns page names the SP type `spGlobalAudiences` and the availability table lists Audience for DSP only (R5).
+- Amazon maps no v1 or Stream v2 equivalent for the audience types, and v1's `audienceSegment.id` covers SP but not SB (R5).
+- Amazon recommends one or two report requests per advertiser per day per type, spread through the day, and taking metadata from exports joined on `campaignId` rather than from reports (R13).
+- Reports hold only entities with activity in the range, and during the v3 Sponsored Brands preview, campaigns with `isMultiAdGroupsEnabled=False` are missing from SB reports (R14).
+
+## Reporting v1
+
+- v1's report operations create, retrieve and delete a report, each answering 207 with one result (R6).
+- A v1 report request holds one report and one period (R6).
+- A v1 report's status is `PENDING`, `PROCESSING`, `COMPLETED` or `FAILED` (R6).
+- A completed v1 report lists up to 100 parts, each with its own pre-signed URL and expiry, partitioned formats splitting into chunks of up to 1 GB uncompressed (R6).
+- A v1 create has no `425` and no idempotency key, and no Amazon page says what an identical create does while its twin runs (R6).
+- Neither API lists reports, so a report is found again only by the id returned at creation (R6).
+- A v1 request is refused synchronously with numbered 400 codes, among them `400004` incompatible fields, `400005` unknown field, `400006` missing field and `400025` past the look-back, and a failed report carries a failure code (R7).
+- A completed v1 report may carry warnings (`NO_PERMISSION`, `PENDING_DEPRECATION`, `DATE_LIMITED`) in a list Amazon says will grow, and warnings never stop it completing (R8).
+- In v1 rows are the group-by of every requested dimension, an attribute needs its primary key, money metrics need `budgetCurrency.value`, and currencies are not summed across budget currencies unless `currencyOfView` converts them (R10).
+- In v1 a missing value is `null` in JSON and `""` in CSV and "does not imply zero"; a measured zero is `0` (R11).
+- v1 keeps daily rows longer than hourly rows, with a cap on the days one request spans, and most v3 types keep their own retention; Amazon's *Dates and historical data retention* page, https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/dates, and the v3 type pages give the figures (R12).
+- Amazon's v3-to-v1 field map gives `keywordId` as `adGroupTarget.id`, `keyword` and `targeting` as `targeting.value`, `keywordType` and `matchType` as `targetingMatchType.value`, `keywordBid` as `adGroupTarget.bid` and `searchTerm` as `searchTerm.value` (R20).
+- The Dimensions library defines no `target.value`, though Amazon's own v1 examples write it and the New features warning example flags it `PENDING_DEPRECATION` (R20).
+- v1 pages document no incompatibility between placement and target, term or hour dimensions, an incompatible pair being refused with `400004`, while v3 has no target-by-placement report (R20).
+- Ad ASIN fields may hold a retailer offer id of another format and length, and v1 product ids pair with their marketplace (R18).
+
+## Limits
+
+- A throttled call answers `429` with `Retry-After` in seconds; limits move with system load and, for reports, with the region's queue (R4).
+- Field reports show `429`s without `Retry-After`: one, filed on 2025-12-04 for a seller in marketplace `A1F83G8C2ARO7P`, persisting over 24 hours on change history, and one, filed on 2026-03-07, from the EU MCP gateway as HTML (R4).
+- Amazon's pages disagree on Reporting v1 concurrency: its limits page and v1 overview say limits apply per client id, shared across every advertiser the client calls for, with concurrency "as low as 1", while the reporting overview, the Stream v2 overview and the GA note say per advertiser (R9).
+
+## Marketing Stream
+
+- Stream v2 delivers Parquet totals at least once to an S3 bucket and SQS queue in the subscriber's AWS account, and the record to keep for a key is the one with the highest `streamBatch.version` (R15).
+- Stream v2's thresholded values fall into an `(Other)` row evaluated at the exact level of detail (R15).
+- A Stream v2 destination belongs to the application that first uses it, at most five per application (R15).
+- ComChatX runs no Stream v2 destination, so hourly data beyond Reporting v1's span is out of cx's reach, which cx can tell a seller who asks for it (R12, R15).
+- Stream v1 carries `keyword_id`, `placement` and the hour in one record until 2027-06-30, and Stream v2's `ads-performance-v1` keys hourly records by placement, target and search term (R20).
+- Stream v1's Sponsored Products datasets are `sp-traffic` and `sp-conversion`, documented on the page whose path is `sp-performance`, with the hour in the profile's time zone (R21).
+
+## Console and seller-side data
+
+- The SP Performance Over Time, SP and SB search term impression share and SP Budget reports exist only in the console, and Amazon treats console-to-API differences above 5% as a support matter (R16).
+- On the seller side, Sales and Traffic aggregates its by-ASIN section over the whole range, and its weeks run Sunday to Saturday (R17).
+- Data Kiosk Economics carries ad charges per MSKU per day, with weeks and months in UTC (R17).
+- Seller Analytics rolls weeks back to Sunday–Saturday, has all metrics ready after about 34 hours, states no time zone for a day, needs the Brand Analytics role and keeps results 30 days (R17).
+- SP invoice postings reach SP-API Finances as `ProductAdsPaymentEvent`, with posted date, charge or refund, invoice id, and base, tax and total (R19).
+
+## Ads API v1, the MCP server and test accounts
+
+- Ads API v1 is one set of create, update, query and delete operations over campaigns, ad groups, ads, targets and associations, which Amazon says will eventually replace the per-product APIs (R22).
+- SP, SB and DSP campaign management on v1 have been GA since 2025; at launch each call is bound to one ad product, with a per-product rate limit and batch sizes (`maxItems`, `maxResults`), SB writes taking far fewer items per call than SP's (R22).
+- The v1 contract and overview also list Sponsored Display and Sponsored Television as supported, and SD has a published v1 specification with no dated GA note (R22).
+- The Amazon Ads MCP server is served from `advertising-ai.amazon.com`, `-eu` and `-fe`, not the Ads API hosts, with the same token and client id, and the `cx-amazon-ads` door, whose origins are the `advertising-api*` hosts, does not reach it (R23).
+- The MCP server's `campaign_management` tools are listed in Amazon's *MCP tools: campaign_management* specification, https://d3a0d0y2hgofx6.cloudfront.net/en-us/mcp/campaign_management.json, among them a single-call SP campaign create whose specification states no response and no behaviour on a failure part-way (R23).
+- As read on 2026-11-09, none of those tools is named for harvesting or negatives, although the MCP server's 2026-02-18 release note describes workflows that "automate keyword harvesting from automatic to manual campaigns" (R23).
+- Amazon serves a skills library on the Ads API hosts, with an `ads-api-migration` skill published on 2026-11-02 (R23).
+- Test accounts serve and bill nothing, are created under a separate `advertising::test:create_account` scope as vendor or author accounts only, and do not run rules (R24).

package/skills/ads-review/references/serving.md

@@ -0,0 +1,50 @@
+# Serving: the Featured Offer, statuses and money stops
+
+## The Featured Offer
+
+- A Sponsored Products or display ad serves only while the advertised product holds the Featured Offer and is in stock, judged at the moment the shopper views it (A8).
+- An advertised product that goes out of stock is paused within its campaign, and a product without the Featured Offer gets zero impressions even when the campaign runs (A8).
+- Amazon's ad rules bind each ad to its own advertiser's offer: SP and Display serve only for the advertised ASIN or SKU that holds the Featured Offer, and the previous holder's impressions stop immediately when it shifts (A25).
+- The Eligibility API answers only for products sold by the profile's merchant, and vendor SP attribution counts only products sold by Amazon (A25).
+- For books, SP ads from an author ads account show only when Amazon itself, not a third-party seller, is the Featured Offer, and a seller's ads only when the seller's own offer is (A25).
+- When another seller holds the Featured Offer on a brand's own ASIN, the brand's SP and display ads for that ASIN serve no impressions, while its Sponsored Brands ads keep serving and send shoppers to a page whose default offer is the other seller's (A9).
+- Amazon routes that case to Seller Support: "Advertising Support can't directly restore Featured Offer eligibility" (A9).
+- Canopy Management, Pattern UK and a seller in the Seller Forums describe spend reaching the other seller's offer (A9).
+- Trellis's page says SP ads "keep running" after a Buy Box loss, against Amazon's page (A9).
+- Rel.ai names Buy Box loss as the most common cause of a sudden SP impression drop, with the console showing a campaign as delivering while its ads are skipped (A9).
+- Amazon's Japanese seller page states that Sponsored Products and Sponsored Display require Featured Offer eligibility, while Sponsored Brands ads are shown even when the advertiser's product is not the Featured Offer (A26).
+- Amazon's AMS-era agency toolkit (August 2017) stated that "ASINs must meet retail financial thresholds to be eligible for promotion through Amazon Marketing Services", that an SP ad paused when the vendor lost the buy box or the ASIN went out of stock and resumed automatically, and that Headline Search needed at least three ASINs in stock and one past the financial threshold (A26).
+- The same toolkit stated that Headline Search and Product Display ads continued to serve when the buy box was lost; for Display, the current Featured Offer page above supersedes it (A26).
+- Ad products and their policy: ../ads-launch/references/products-and-policy.md.
+
+## Featured Offer eligibility in 2026
+
+- Amazon announced on 2026-07-06 that "Starting in July 2026, we'll begin removing seller eligibility requirements for the Featured Offer", rolling out gradually and completing by the end of 2026, and that "We're not changing how the Featured Offer is selected" (A10).
+- Seller Central's *Featured Offer eligibility* page as captured on 2026-10-14 reads "As of September 2026, Amazon no longer maintains a seller eligibility requirement", while the ads guides read on 2026-11-09 still say an advertised product "must be eligible to be the featured offer" (A10).
+
+## Product eligibility
+
+- The Eligibility API's product eligibility check takes ASINs, SKU optional, and an ad type (`sp` by default, `sb`, `sd` or `dsp`), and returns per-product statuses, each `INELIGIBLE` or `ELIGIBLE_WITH_WARNING`, that include `NOT_IN_BUYBOX`, `OUT_OF_STOCK` and `INELIGIBLE_PRODUCT_COST` (A27).
+- The SP 3.0 serving-status reasons include `CP_INELIGIBLE`, `CP_INELIGIBLE_ASIN`, `CP_INELIGIBLE_UNKNOWN` and `CP_INELIGIBLE_VENDOR`, which Amazon's model does not describe (A27).
+- CNBC reported in 2019 that Amazon emailed vendors that products "no longer qualif[y] for advertising" because their sale "currently results in a loss to Amazon", glossing the practice as CRaP ("Can't Realize a Profit"), a term no Amazon page read in 2026 uses (A27).
+- Flywheel (Gabe Fishbein, 2024) reports a rise in ASINs becoming ineligible for Sponsored Products after Amazon re-evaluated "safe-listed" unprofitable ASINs, in their account only SP placements being affected and some ASINs restored through Amazon reps (A27).
+- MerchantSpring (Rachel Seiton) and SellerApp (Brij Purohit) state that a CRaP-flagged product loses Sponsored Products or advertising eligibility and that Amazon may then stop issuing purchase orders for it (A27).
+
+## Serving statuses and delivery reasons
+
+- Sponsored Products v3 returns the serving status of every entity in `extendedData` when extended data is requested, with values such as `AD_NOT_IN_BUYBOX`, `AD_OUT_OF_STOCK` and `AD_NO_PURCHASABLE_OFFER` (A15).
+- Sponsored Brands and Sponsored Display keep their own, largely shared enums (A15).
+- The extended-data flag's request description and the response schema name the fields differently, and extended-data list calls weigh five times a standard call against the rate limit (A15).
+- In Ads API v1 an entity carries a user-set `state` (`DRAFT`, `PROPOSED`, `ENABLED`, `PAUSED`, `ARCHIVED`) and a separate `status.deliveryStatus` (`DELIVERING`, `LIMITED`, `NOT_DELIVERING`, `UNAVAILABLE`) with `deliveryReasons` (A16).
+- SP v1 writes accept `ENABLED` and `PAUSED` only (A16).
+- Amazon Ads Status publishes six months of incidents by region and category (ad delivery, campaign management, reports, Marketing Stream) as a page and a `history.json` (A19).
+
+## Money stops
+
+- Every money stop has a name: SP serving statuses and v1 delivery reasons distinguish campaign, portfolio and account out of budget, payment failure and prepay balance (A17).
+- A portfolio's state shows in its campaigns' reasons (A17).
+- Sponsored Brands v4 lists `PORTFOLIO_OUT_OF_BUDGET`, although the common enums page does not (A17).
+- When Amazon cannot charge the default payment method the account's campaigns pause, while a backup method, if one is set, is charged without pausing them (A18).
+- Amazon retries at a fixed frequency and reactivates when a payment succeeds (A18).
+- Seller-account charges come from Funds Available, not Total Balance (A18).
+- Billing notifications carry an impact (`CAMPAIGNS_SUSPENDED` or `NO_IMPACT`), a severity and a suspension date, and the billing API reports each account's billing state (A18).

package/skills/ads-review/references/vendors.md

@@ -0,0 +1,25 @@
+# Vendors: profiles, purchase orders and supply
+
+## Vendor profiles
+
+- A vendor profile's `accountInfo.type` is `vendor`, and Amazon says vendor accounts are used with Sponsored Products, Sponsored Brands and Sponsored Display only (A24).
+- In the Profiles 3.0 model `validPaymentMethod` is present only for vendors, the profile `dailyBudget` and profile updates are for sellers only, and `accountInfo.id` is not unique and may repeat across marketplaces (A24).
+
+## Purchase orders
+
+- Amazon places purchase orders with vendors through the Vendor Orders API; its PO types are RegularOrder, ConsignedOrder, NewProductIntroduction and RushOrder (A28).
+- An order's state is New, Acknowledged or Closed, while the status call reports OPEN or CLOSED (A28).
+- A vendor acknowledges each line as Accepted, Backordered or Rejected, with rejection reasons TemporarilyUnavailable, InvalidProductIdentifier or ObsoleteProduct (A28).
+- Amazon Science states that Amazon's buying systems determine how much of each product to purchase from different suppliers, and that vendor lead times vary with manufacturing capacity, transport and weather (A28).
+- Amazon defines procurability as "whether Amazon is able to fulfill a customer delivery promise, considering the ability of known vendors to supply the ASIN in the foreseeable future" (A28).
+
+## Supply reports
+
+- The vendor inventory report and Data Kiosk report the supply behind a vendor's availability: procurable out-of-stock rate (out-of-stock glance views on procurable ASINs over total glance views), vendor confirmation rate (confirmed over submitted units), receive fill rate (received over confirmed units), open PO units, average vendor lead time, units in the most recent POs of the week, and sellable on-hand units, in which backorders count as negative units (A29).
+- The real-time inventory report gives hourly highly-available inventory per ASIN, can be requested five minutes after each hour closes, looks back 30 days and spans 7, and is also offered as the `ITEM_INVENTORY_EVENT_CHANGE` notification (A29).
+- The forecasting report gives mean, P70, P80 and P90 weekly demand forecasts per ASIN for the latest forecast only, one store per request (A29).
+- Its schema defines P80 as the units with which there is an 80% probability the ASIN will not run out of stock during the period, and the Analytics page as an 80% probability that customer demand will not exceed the weekly forecast (A29).
+
+## A practitioner's reading
+
+- Intentwise (Michael Waters, 2023) states that Vendor Central takes about 48 hours to refresh inventory data, and that Amazon auto-pauses Sponsored Products for out-of-stock products but not Sponsored Brands, Sponsored Display or DSP, a line set against Amazon's current Featured Offer page for Display (A30).

package/skills/ads-search-terms/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ads-search-terms
+description: "What shoppers' search terms and negatives look like in a seller's sponsored ads: what the search term report and the bulksheet search term tab hold and leave out, how negative keywords and negative product and brand targets work at each level in Sponsored Products, Sponsored Brands and Sponsored Display, where Amazon's own texts disagree, Amazon's own harvest, and how practitioners and research judge a term with clicks and no orders. For reading search terms, harvesting them or adding negatives in a seller's ads."
+---
+
+## The report
+
+- The Ads API search term report holds only clicked terms; Amazon's texts disagree on whether the console report holds impressions. (S1)
+- The SP search term report has no advertised-ASIN column. (S3)
+- `*` is a detail-page placement; ASIN-shaped terms are detail pages, on auto and product-targeting rows only; negative ASIN targets stop ads on such pages, negative keywords on search pages for matching queries. (S2, S5)
+- The bulksheet search term tab always looks back 7 days. (S15)
+
+## Negatives
+
+- Negative ASIN and brand targets act only on product-attribute and automatic targets. (S5)
+- Negatives sit at ad group or campaign level; an SP campaign negative keyword covers every ad group, an ad-group one only its own; SB has "no campaign-level negative targeting", SD's are ad-group level. (S6)
+- Amazon states a negative keyword takes effect within 72 hours, a negative product 96. (S8)
+- An existing negative keyword's match type cannot be changed. (S7)
+- Console help and bulksheets offer negative exact and phrase only; SP 3.0 and v1 also accept broad. (S9)
+- No Amazon model, help page or bulksheet tab read on 2026-11-09 carries a shared negative keyword list or portfolio-level negatives. (S23)
+
+## Terms
+
+- Amazon's targeting guide puts a minimum click count and a period before judging, and recommends phrase or exact for negatives. (S13)
+- Practitioners' points for a term with clicks and no orders differ, tied to price, margin or conversion rate. (S17)
+- With zero conversions in n clicks, the 95% upper bound on conversion rate is about 3/n, good for n over 30. (S20)
+- Delayed-feedback models treat not-yet-converted recent clicks as uncertain, not negative. (S21)
+- Target promotion groups are Amazon's harvest from auto into manual ad groups, its Target Promotion guide describing no negative in the source; several practitioners negate a term moved to exact at its source, Adbrew calling its move thresholds "practitioner defaults … not Amazon rules". (S14, S18)
+
+## References
+
+- references/search-term-report.md: rows, columns, bulksheets.
+- references/negatives.md: levels, match types, writing, conflicts.
+- references/terms.md: thresholds, harvest, small counts.
+- ../ads-change/references/tests.md: Amazon's click and week figures.
+- ../ads-structure-and-targets/references/structure.md: ad groups, per-ASIN structures.
+- ../ads-review/references/reports.md: report types, advertised product.
+- ../ads-review/references/metrics.md: metric definitions.

package/skills/ads-search-terms/references/negatives.md

@@ -0,0 +1,51 @@
+# Negatives
+
+## What a negative stops
+
+- Negative keywords stop ads on search pages for matching queries. (S5)
+- Negative ASIN and brand targets stop ads on those detail pages and act only on product-attribute and automatic targets. (S5)
+- These targets act in the ad group or, at campaign level, in every ad group, and they can name the advertiser's own pages or a competitor's. (S5)
+- Amazon states a buffer before a negative takes effect: up to 72 hours for negative keywords and 96 hours for negative products. (S8)
+
+## Levels
+
+- Negatives exist at two levels only, ad group and campaign (`TargetLevel` `AD_GROUP`, `CAMPAIGN`). (S6)
+- In Sponsored Products a campaign negative keyword applies to every ad group of the campaign, and an ad-group one to that ad group only. (S6)
+- Sponsored Brands has "no campaign-level negative targeting", and Sponsored Display negatives are ad-group level. (S6)
+- Each Sponsored Products bulksheet negative row carries its campaign id and, at ad-group level, its ad group id, with match type `negativeExact` or `negativePhrase`; a row with a blank Operation is ignored on upload. (S6)
+
+## Match types
+
+- Negative phrase blocks queries containing "the complete phrase or close variations", and negative exact "the exact phrase or close variation". (S7)
+- Negative phrase is limited to 4 words and negative exact to 10, each at most 80 characters; these figures were read from Amazon's help and API limits pages on 2026-11-09. (S7)
+- The match type of an existing negative keyword cannot be changed. (S7)
+- The console help and bulksheets offer negative exact and phrase only, while the Sponsored Products 3.0 and v1 models also accept a broad negative match type, and one keyword guide mentions "exact, phrase, or broad". (S9)
+- AMALYZE writes "There is no negative broad". (S9)
+- Practitioners disagree on whether negative phrase is order-sensitive: Ad Badger and Scale Insights say it blocks the words in sequence, JumpFly says in any order. (S19)
+
+## Where negatives are written
+
+- In v1 a negative keyword, ASIN or brand is a target created with `negative: true` on v1's create-targets operation, and v1's query-targets operation filters by `negativeFilter`. (S10)
+- Sponsored Products 3.0 writes negatives as ad-group negative keywords, campaign negative keywords and negative targets. (S24)
+- Sponsored Brands writes them as negative keywords and negative targets, at most 100 per call. (S24)
+- Sponsored Display writes ad-group negative targeting clauses, and the Sponsored Display 3.0 model has no negative keyword operation. (S24)
+- The v1 target tables have no Sponsored Display column, while the v1 `AdProduct` enum and the campaign-management overview include it, and no release note of 2026, as read on 2026-11-09, announces it in v1 campaign management. (S24)
+
+## Campaign-level negative product targets
+
+- Three Amazon texts conflict on campaign-level negative product targets in a seller's manual Sponsored Products campaign. (S11)
+- The API guide says vendors only. (S11)
+- The 2025-05-22 release note says every US campaign and ad group has the same negative options. (S11)
+- The Sponsored Products 3.0 model says campaign negative targeting clauses are "only available for AUTO campaigns". (S11, S24)
+
+## Amazon's brand-negative recommender
+
+- Amazon's brand-negative recommender for Sponsored Products and Sponsored Brands includes the advertiser's own brands, "because targeting your own brands usually results in lower performance than targeting competitors' brands". (S12)
+- The statement names no metric and shows no data. (S12)
+
+## Shared lists
+
+- No Amazon model, help page or bulksheet tab read on 2026-11-09 carries a shared negative keyword list or portfolio-level negatives. (S23)
+- Karooya wrote in 2019 that "the shared negative keyword list has been missing from Amazon Ads", and its tool adds each list entry as campaign-level negative keywords in every associated campaign. (S23)
+- RedHen Labs wrote on 2026-08-27 (read 2026-11-09), naming no marketplace, that it kept 69 campaign-level exact negatives across 43 campaigns. (S23)
+- SellerSprite writes that Amazon allows reusable negative keyword lists and that portfolios can carry negatives across campaigns. (S23)

package/skills/ads-search-terms/references/search-term-report.md

@@ -0,0 +1,31 @@
+# The search term report
+
+## What has a row
+
+- The Ads API search term report, in reporting v3 and in v1, holds only terms with at least one ad click, so a term with impressions and no click has no row. (S1)
+- Amazon's console help says the same of the console report, while its v3 FAQ says the console report also holds impressions; the two texts have not been reconciled. (S1)
+
+## What a term looks like
+
+- A search term of `*` is a detail-page placement with no keyword. (S2)
+- ASIN-shaped terms are the detail pages the ad appeared on, and they show only on auto and product-targeting rows. (S2)
+- A negative ASIN target stops ads on such a detail page, while a negative keyword stops ads on search pages for matching queries. (S2, S5)
+
+## Columns
+
+- The Sponsored Products search term report carries the keyword or targeting expression, the match type, and the ids of keyword, ad group and campaign. (S3)
+- It has no advertised-ASIN column. (S3)
+- ../ads-structure-and-targets/references/structure.md: what products in one ad group share, and practitioners' per-ASIN structures.
+- ../ads-review/references/reports.md: report types and columns across ad products.
+
+## Sponsored Display's matched target
+
+- The matched target dimension (v3 `matchedTargetAsin`) holds the detail pages an ad appeared on that drew at least one click, and it exists for Sponsored Display only. (S4)
+- One developer reports that since mid-July 2026 it carries no customer search terms, also for past dates re-requested, and Amazon has not answered the report. (S4)
+
+## The bulksheet search term tab
+
+- The bulksheet search term tab always uses a 7-day lookback, whatever the file's range. (S15)
+- It carries the source campaign, ad group, keyword and target ids. (S15)
+- Its page defines CTR and conversion rate inverted. (S15)
+- ../ads-review/references/metrics.md: how each metric is defined.

package/skills/ads-search-terms/references/terms.md

@@ -0,0 +1,41 @@
+# Judging and harvesting terms
+
+## Amazon's guide
+
+- Amazon's targeting guide puts a minimum click count before judging a keyword for a negative and a period before judging a negative, and recommends phrase or exact for negatives. (S13)
+- ../ads-change/references/tests.md: the same guide's click count and period, quoted in figures.
+
+## Practitioners' thresholds
+
+- Practitioners judge a term with clicks and no orders at different points and tie the count to price, margin or conversion rate. (S17)
+- The practitioner figures below are as their pages read on 2026-11-09, and none of those pages names a marketplace. (S17)
+- Ad Badger (Michael Erickson Facchin) negates at 2,500 impressions with CTR under 0.18% and no conversions, more than $35 spend with no conversions, or more than 34 clicks without one, calls these "starting points" and exempts competitor brand terms. (S17)
+- Jungle Scout (Galeana) judges at 10 clicks; Seller Labs at 20–30; Canopy at 20–30 for $30–100 products and 40–50 above $100. (S17)
+- Scale Insights' default "Unique Word with 0 Sales" filter is at 25 clicks per word, not per term. (S17)
+- Scale Insights' word rule aggregates single words across search terms per product and adds non-performing words as ad-group negative phrase, skipping singular and plural forms of words in the product title. (S17)
+- Ad Badger's PPC Den page says branded terms may convert every couple of clicks where competitor terms may need fifty, and that one rule across the board kills keywords "that were slow, not bad". (S17)
+
+## Harvesting
+
+- Sponsored Products target promotion groups are Amazon's own harvest: they link an auto ad group to manual destination ad groups and move converting search terms and ASINs into them. (S14)
+- They move them on recommendations "based on performance heuristics" that the specification does not state. (S14)
+- The Target Promotion guide does not describe adding negatives in the source. (S14)
+- Several practitioners add a term moved to exact as a negative where it came from. (S18)
+- Seller Labs adds it as negative exact in the auto campaign, and Canopy in auto and broad. (S18)
+- Ad Badger adds it in broad and auto for a term kept in exact at a lower bid. (S18)
+- Helium 10's Prestozon rule adds it as negative exact in the broad ad group and negative phrase in the auto campaign. (S18)
+- Adbrew negates a term that reaches exact in every auto, broad and phrase campaign of its product group. (S18)
+- Adbrew (Ayush Chaudhary, 2026-10-27, read 2026-11-09, naming no marketplace) moves a term to phrase at one order in 30 days within 1.5× target ACoS and to exact at two orders at or under target, excludes the last 7 days, and calls these "practitioner defaults … not Amazon rules". (S18)
+
+## Small counts
+
+- With zero conversions in n clicks, the 95% upper bound on the conversion rate is about 3/n, the rule of three, a good approximation when n is greater than 30 (Hanley and Lippman-Hand). (S20)
+- At single-keyword sample sizes the normal-approximation interval for a conversion rate has poor coverage, and the Wilson and Jeffreys intervals perform better (Brown, Cai and DasGupta). (S20)
+- Ratio metrics such as CPC and ACOS need delta-method variance (Deng, Knoblich and Lu). (S20)
+- Conversions can arrive long after the ad interaction, and delayed-feedback models treat not-yet-converted recent clicks as uncertain rather than negative (Chapelle). (S21)
+- In paid search, keyword conversion data are sparse and position is endogenous (Rutz, Bucklin and Sonnier). (S21)
+- In that research, a keyword list built on estimated conversion rates outperformed lists built on observed conversion and click-through rates. (S21)
+
+## Relevance labels
+
+- Amazon's ESCI dataset labels query-product pairs Exact, Substitute, Complement or Irrelevant (Reddy et al.). (S22)

package/skills/ads-seasons/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ads-seasons
+description: "Sponsored ads around Amazon's sales events: the Prime Day, Prime Big Deal Days and Black Friday calendars by region, the Ads API's events and event themes, what Amazon and practitioners report on budgets, CPC and conversion before, during and after a peak, how attribution and benchmarks read across a moving event, and the deals, promotions and claim rules beside the ads. For reading or changing a seller's sponsored ads around a sales event."
+---
+
+## Calendar
+
+An event's dates and length differ by marketplace and year; SP's events operation returns suggested date ranges for the advertiser's marketplace. (E1, E2, E3)
+Since 2019 Prime Day's start has moved between June and October; in 2025 it went from 48 to 96 hours. (E1)
+
+## Events in the Ads API
+
+Budget-rule event recommendations (`EVENTS_FOR_EXISTING_CAMPAIGN`) give an SP or SB campaign Amazon's recommended events, each with a `suggestedBudgetIncreasePercent`; a rule tied to an unannounced event is created with empty dates that Amazon fills in on announcement. (E3)
+Theme-based bid recommendations offer `PRIME_DAY`, `FALL_PRIME_DEAL_EVENT` and `BFCM_HOLIDAY`. (E4)
+
+## Spend and performance
+
+Amazon advises daily budgets +20–30% around Black Friday and Cyber Monday, three to five days ahead, as guidance, not limits; Ad Badger recommends 2–3× on Prime event days. (E5, E6)
+How a budget rule raises a budget: ../ads-bids-and-budgets/references/budgets.md.
+Amazon says conversion rates often drop during major sales events and that a temporary ACOS spike is read against TACOS. (E7)
+Practitioners disagree on post-event spend and on December 26 to mid-January, their "Q5", unused by any Amazon page read 2026-11-09. (E16, E20, E5)
+
+## Reading an event
+
+SP attributes seller conversions over 7 days, SB and SD over 14, dated to the ad interaction; Amazon advises checking 7–14-day attribution before changing campaigns after a peak. (E8)
+A moving event lands in different Data Kiosk year-over-year benchmark weeks. (E15)
+Store-level scanner research puts the post-promotion dip at 4–25% of the promotion's current sales effect, usually missed by simple models and visual inspection. (E18)
+
+## Deals and claims
+
+An advertised deal must be live whenever the ad is; sponsored ads mention Prime Day only through dynamically pulled detail-page information such as deal badges. (E13)
+Amazon's ad policy bounds an event's name in an ad, such as "Black Friday Week", by the event's length, as its Event days page for that marketplace states (https://advertising.amazon.com/help/GQ3SJ5QCWCQCKCYQ). (E1, E13)
+
+## References
+
+- references/calendar.md: where event dates are read; history.
+- references/api-events.md: events, budget-rule events, themes.
+- references/spend.md: budgets, CPC, conversion, post-event.
+- references/measurement.md: attribution, benchmarks, promotion research.
+- references/deals.md: deals, fees, promotions, emails.
+- references/claims.md: badges, ad policy, Stores, EU prices.
+- references/vendors.md: vendor promotions.
+- The amazon-ads skill's references/door.md: report requests.
+- ../ads-change/references/history.md: change history.

package/skills/ads-seasons/references/api-events.md

@@ -0,0 +1,24 @@
+# Events and themes in the Ads API
+
+## Events
+
+Amazon's Sponsored Products events operation returns individual and grouped special events with suggested date ranges in the advertiser's marketplace, each with an `eventId`. (E3)
+Budget-rule event recommendations (`EVENTS_FOR_EXISTING_CAMPAIGN`) return, per campaign, the events Amazon recommends with a `suggestedBudgetIncreasePercent`. (E3)
+Amazon chooses those events from the campaign's products, and they change when the products change. (E3)
+Recommended events exist for Sponsored Products and Sponsored Brands only. (E3)
+A budget rule tied to an unannounced event is created with empty dates, which Amazon fills in when the dates are announced. (E3)
+Budget rules at large: ../ads-bids-and-budgets/references/budgets.md.
+
+## Themes
+
+Theme-based bid recommendations offer `PRIME_DAY`, `FALL_PRIME_DEAL_EVENT` and `BFCM_HOLIDAY` beside `CONVERSION_OPPORTUNITIES`. (E4)
+They are computed from recent winning bids for similar products, and their impact estimates assume the campaign does not run out of budget. (E4)
+In Ads API v1, `Bid.theme` carries the same four values. (E4)
+Keyword recommendations offer a `SPECIAL_DAYS` theme for high sales events such as Prime Day. (E4)
+The v1 target model offers the theme targets `KEYWORDS_RELATED_TO_PRIME_DAY`, which matches queries only through the end of Prime Day, and `KEYWORDS_RELATED_TO_GIFTS`. (E4)
+The SP 3.0, SB 3.0 and SB 4.0 specs read do not carry the Prime Day theme. (E4)
+
+## Amazon Business
+
+On Amazon Business the business-shopper bid adjustment goes up to 900%. (E19)
+Amazon suggests a business-shopper adjustment of 20–120% for Prime Day and 20–50% for about two weeks around the holidays. (E19)

package/skills/ads-seasons/references/calendar.md

@@ -0,0 +1,27 @@
+# Event calendar
+
+An event's dates, hours and countries differ by marketplace and year. (E1, E2)
+Amazon's Sponsored Products events operation returns special events with suggested date ranges in the advertiser's marketplace. (E3)
+
+## Prime Day
+
+The Amazon Ads "Prime Day" events page (https://advertising.amazon.com/events/prime-day) gives Prime Day's dates and the countries it runs in, and aboutamazon's "When is Amazon Prime Day" (https://www.aboutamazon.com/news/retail/when-is-amazon-prime-day) its US hours. (E1)
+The countries where Prime Day comes to Amazon Business are listed in Amazon Ads' "Prime Day 2026: Advanced advertising strategies" (https://advertising.amazon.com/library/guides/prime-day-guide-advanced-strategies). (E1)
+Since 2019 Prime Day has started as early as June (2021) and as late as October (2020), as aboutamazon's "The history of Prime Day" records (https://www.aboutamazon.com/news/retail/the-history-of-prime-day). (E1)
+Prime Day changed from 48 to 96 hours in 2025. (E1)
+
+## Autumn and holiday
+
+Prime Big Deal Days' US dates and hours are on aboutamazon's "Prime Big Deal Days FAQ" (https://www.aboutamazon.com/news/retail/amazon-prime-big-deal-days-faq). (E1)
+Its local start time differs by marketplace, and Germany calls it "Prime Deal Days": About Amazon UK's Prime Big Deal Days page (https://www.aboutamazon.co.uk/news/retail/amazon-prime-big-deal-days-2026-date) gives the UK's start time, About Amazon EU's Prime Big Deal Days page (https://www.aboutamazon.eu/news/retail/prime-big-deal-days-2026) the European start time and countries, and About Amazon Deutschland's "Was sind die Amazon Prime Deal Days?" (https://www.aboutamazon.de/news/amazon-prime-und-shopping/prime-deal-days-termine-angebote) the German dates. (E2)
+Amazon's German release says dates may vary by country. (E2)
+The US Black Friday and Cyber Monday dates are on aboutamazon's "When is Black Friday 2026? Here's everything you need to know" (https://www.aboutamazon.com/news/retail/when-is-amazon-black-friday-faq) and "When is Cyber Monday 2026?" (https://www.aboutamazon.com/news/retail/when-is-amazon-cyber-monday-faq). (E1)
+Amazon Japan gives its Black Friday dates on aboutamazon.jp's "Amazon ブラックフライデー 2026" (https://www.aboutamazon.jp/news/retail/amazon-black-friday-2026). (E1)
+As read on 2026-11-09, that page had not announced them. (E1)
+Amazon gives Black Friday Week's UK and German dates in UK and German releases; the Amazon Press Center DE archive (https://press.aboutamazon.com/press-release-archive?f0=de-DE) is an index of the German releases, and About Amazon UK's retail news (https://www.aboutamazon.co.uk/news/retail) an index of the UK's event news. (E2)
+As read on 2026-11-09, neither index listed a 2026 announcement of those dates. (E2)
+
+## Regional calendars
+
+Amazon's spring event runs under its own name and dates in the UK ("Spring Deal Days") and Germany ("Frühlingsangebote"), announced in releases indexed on About Amazon UK's retail news (https://www.aboutamazon.co.uk/news/retail) and in the Amazon Press Center DE archive (https://press.aboutamazon.com/press-release-archive?f0=de-DE), and as the Big Spring Sale in the US, on aboutamazon's US "Big Spring Sale FAQ" (https://www.aboutamazon.com/news/retail/amazon-big-spring-sale-faq). (E2)
+India's Great Indian Festival runs for weeks across the festival calendar, and aboutamazon.in's "Amazon Great Indian Festival" (https://www.aboutamazon.in/amazon-great-indian-festival) gives its dates. (E2)

package/skills/ads-seasons/references/claims.md

@@ -0,0 +1,35 @@
+# Deal creative and claims
+
+## Deal badges in ads
+
+Responsive eCommerce Creative renders a deal badge automatically when the product qualifies for Deal of the Day, a Lightning Deal or a Best Deal, and a BFCM badge at BFCM, only on the "Shop now" variation. (E12)
+Its custom headline may not contain a price or deal. (E12)
+A Sponsored Brands product collection featuring products on deal automatically shows a deals call-to-action and a seasonal lifestyle image. (E12)
+Since August 2026 a Product Collection create makes a Manual Collection ad. (E12)
+Amazon dates the Product Collection format's end twice: create errors after January 2027, and "Beginning February 2027" in a release note. (E12)
+
+## Ad policy on deals
+
+An advertised deal must be live whenever the ad is: Amazon allows no deal teasing. (E13)
+The price or saving appears in the same format on ad and landing page, and promotional claims match the landing page for the whole campaign. (E13)
+Numeric prices or savings are allowed only where Amazon renders them dynamically, and pricing superlatives are prohibited. (E13)
+"Up to X%" needs at least 10% of the promoted ASINs at or above X%. (E13)
+A claim made inaccurate by dynamic pricing requires pausing the creative and changing it to a qualified claim. (E13)
+An event's name in an ad, such as "available on Black Friday only" or "Black Friday Week", is bounded by the event's length, as Amazon's Event days page for that marketplace states (https://advertising.amazon.com/help/GQ3SJ5QCWCQCKCYQ). (E1, E13)
+Sponsored ads may not mention Prime Day except through dynamically pulled detail-page information such as deal badges, and may not use "Prime" outside "Prime Day". (E13)
+Ad products and ad policy at large: ../ads-launch/references/products-and-policy.md.
+
+## Brand Store
+
+In a Brand Store, promotional messaging is allowed only with the Featured Deals widget (at least four ASINs). (E13)
+Sales-event content in a Store may start no more than seven days before the event and is removed within 24 hours after, and a Store version is submitted at least 48 hours ahead. (E13)
+Store pages may not name Amazon events or numerical discounts. (E13)
+
+## Reference prices in Europe
+
+German law (PAngV § 11) requires an announced price reduction to state the lowest price of the prior 30 days. (E23)
+The EU Court of Justice held, in 2024, that a reduction announced as a percentage or as an advantageous price must be computed from that 30-day low. (E23)
+Amazon's French, Spanish, Italian, Belgian, Swedish and Polish stores display that 30-day low for price-reduction announcements and give the "Was Price" as a 90-day median excluding promotional prices. (E23)
+Amazon.co.uk shows "Lowest price in 30 Days" when the price is at or below the past 30 days' lowest featured-offer price. (E23)
+Amazon.de's page says event badges such as Black Friday can be added to an already active deal, and carries no 30-day sentence. (E23)
+The Munich I Regional Court ruled Amazon's October 2024 "Prime Deal Days" price advertising unlawful where discounts were computed from the RRP or a customer average price, which Amazon said it would appeal, as heise online reported on July 16, 2025. (E23)