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

package/skills/ads-bids-and-budgets/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ads-bids-and-budgets
+description: "What a sponsored ad's click costs and how its spend runs: Amazon's auction and reserves, Sponsored Products bidding strategies, placement and audience adjustments, bid and budget rules, Sponsored Brands and display cost control, daily, lifetime and portfolio budgets and their pacing, how bids and budgets are written, and the changes Amazon and outside tools make themselves. For reading, judging or changing a seller's bids and budgets in Sponsored Products, Sponsored Brands and Sponsored Display."
+---
+
+## Auction
+
+- A bid is the most an advertiser authorises per click or 1,000 viewable impressions; Amazon states it never charges above the maximum effective bid, adjustments and strategy included, and its soft reserves can make a winner pay its own bid. (B1)
+
+## Bidding
+
+- SP strategies: `LEGACY_FOR_SALES` (down only), `AUTO_FOR_SALES` (up and down), `MANUAL`, `RULE_BASED`; an API-created campaign with no strategy gets `LEGACY_FOR_SALES`, so down only may be nobody's choice. (B5)
+- Under up and down, Amazon's help and API models allow up to 100% at every placement, while its author-facing guide still gives 50% outside top of search; no page dates a change. (B6)
+- SP placement adjustments run 0–900%; dynamic bidding works on the adjusted bid; kinds of adjustment multiply. (B7, B8)
+- Rule-based bidding needs at least 10 days running, 10 conversions in the last 30 and the minimum daily budget Amazon publishes per marketplace. (B11)
+- Its ROAS guardrail rests on the previous 21 days and is not guaranteed; Amazon warns an aggressive one can reduce conversions. (B11)
+- SB and display cost control set a target average CPC, not a maximum. (B16)
+
+## Budgets
+
+- A daily budget is averaged over the calendar month; one day may spend up to 100% more (25% if opted out). (B22)
+- Sponsored-ads budgets are not paced; an out-of-budget campaign waits for midnight. (B23)
+- SP/SB/SD campaign budget usage returns `budgetUsagePercent`, spend over the day's effective budget, with `usageUpdatedTimestamp`; Trellis advises recording when each campaign ran out. (B25, B33)
+- The SP budget recommendation returns a suggested daily budget, the last 7 days' share in budget and estimated missed impressions, clicks and sales, "not a guarantee"; missed sales are click-attributed, not ad-caused. (B26)
+- Budget rules only raise budgets; SP reads the raised one as `budget.effectiveBudget`. (B27)
+- A portfolio cap stops its campaigns with `PORTFOLIO_OUT_OF_BUDGET`. (B28)
+
+## References
+
+- references/auction.md: reserves, FTC case, position research.
+- references/bidding.md: strategies, placement caps, rule-based and schedule rules, adjustments, practitioners.
+- references/budgets.md: averaging, pacing, usage, recommendations, budget rules, portfolios, tools.
+- references/writes.md: limits, refusals, bid and budget writes.
+- references/automation.md: Amazon's own changes, recommendations, agents, bid tools, lifts.
+- Calls: the amazon-ads skill's references/door.md.
+- Metrics, reports: ../ads-review/references/metrics.md, ../ads-review/references/reports.md.

package/skills/ads-bids-and-budgets/references/auction.md

@@ -0,0 +1,38 @@
+# The auction and what a click costs
+
+## Bid and price
+
+- A bid is the maximum an advertiser authorises per click, or per 1,000 viewable impressions. (B1)
+- Amazon describes "a form of generalized “second-price” auction" with a hard reserve a bid must exceed to enter and soft reserves set in real time. (B1)
+- In Amazon's description, a winner above both reserves pays the soft reserve; a winner above the hard reserve but below the soft one still wins and pays its own bid. (B1)
+- Amazon states that "the price charged to you may exceed the runner-up bid". (B1)
+- Amazon states that reserves move with factors including predicted sale likelihood, predicted return on ad spend, competing bids, placement, context and peak periods, and "aren't predictable in advance by anyone, including Amazon or the advertiser". (B1)
+- Amazon states that it never charges more than the maximum effective bid, which includes bid adjustments and the bidding strategy. (B1)
+- Chuck Kessler (Canopy Management) quotes Amazon's wording that the final CPC "will never exceed your maximum adjusted bid" and holds that the gap between bid and average CPC is the advertiser's only account-specific read on the price cushion. (B1)
+- Amazon ranks ads by relevance and bid and states that ads with lower bids and higher relevance "can and do win". (B2)
+
+## The FTC case
+
+- The FTC and 22 states allege, in a complaint of 2026-08-31 that is untested, with trial set for 2027-03-29, that an undisclosed soft reserve "beginning in 2019" made Sponsored Products advertisers pay their own bid 30–40% of the time in 2021, 70% in 2022 and about 80% in 2024. (B3)
+- The complaint also alleges that Amazon raised reserve-price surcharges during Prime Day and other high-velocity events. (B3)
+- It alleges that Amazon more than doubled top-of-page desktop ads in one year although an internal study found higher ad loads "decreases purchase rates and increases search abandonment". (B3)
+- Texas, suing separately the same day, alleges soft reserves lift the winner's cost by roughly 17% on ordinary days and more than 25% at peak events. (B3)
+- Amazon disputes the characterisation. (B3)
+- Amazon states that inflation-adjusted SP search CPC was flat from 2019 to 2024 while conversion rates rose 24% from 2021 to 2025. (B3)
+- Amazon states that about 92% of selected SP ads in 2024 were not the highest bid, and that competitors' average bids on keywords fell about 83% in one study when one advertiser stopped bidding. (B3)
+
+## Auction research
+
+- In auction research, reserve prices raised a search engine's revenues "substantially" in a large field experiment. (B4)
+- In the generalized second-price auction a bidder's price per click depends on the bids and quality of the advertiser ranked below it. (B4)
+- Researchers at Amazon Ads and Outreach describe a soft floor under which a bidder still wins and pays its own bid. (B4)
+- In their simulation, soft floors barely change revenue with symmetric single-query bidders but can change it when bidders choose which queries to target. (B4)
+- Ad Badger holds that an advertiser can infer its auction pricing only from its own account, as average CPC over the current bid per target, with ratios near 0.90–1.00 meaning effectively first-price. (B4)
+
+## Position
+
+- Published web-search studies disagree on how conversion rate moves with ad position: highest at the top (Ghose & Yang), raised by higher positions (Rutz, Bucklin & Sonnier), rising lower down (Agarwal, Hosanagar & Smith, who also find profit can be higher below the top); none of the four is on Amazon. (B21)
+- Narayanan & Kalyanam's regression-discontinuity design finds naive position comparisons biased by auction selection, and causal effects much smaller, present only at some positions, larger for smaller advertisers and less experienced consumers, and weaker for brand- or product-specific keywords and exact match. (B21)
+- Click-model research finds click probability depends on position apart from relevance. (B21)
+- A field experiment found more rival ads above the organic results raised the top sponsored listing's click-through rate. (B21)
+- Walmart's and Amazon researchers' sponsored-products systems treat position as a confounder and de-bias for it. (B21)

package/skills/ads-bids-and-budgets/references/automation.md

@@ -0,0 +1,59 @@
+# Amazon's suggestions, its own changes and outside tools
+
+## Suggested bids
+
+- Suggested bids and ranges are calculated from bids of similar ads that won impressions over the past 7 days, offered as low, median and high and updated daily, so they exist for an ASIN with no history of its own. (B13)
+- The console gives a separate suggestion for events in the next 45 days. (B13)
+- The SP target bid recommendation returns up to three values per target by theme, and its v5 version adds impression estimates. (B13)
+- Its per-placement analysis is available only for existing ad group requests, in the marketplaces the Sponsored Products 3.0 model names in its v5 content type's description. (B13)
+- Performance Estimate figures and the old theme-based impact metrics are not a forecast and do not consider budget constraints. (B13)
+- The v2 SP target bid recommendations and the v3 theme-based version of the SP target bid recommendation were announced for shutoff on 2025-05-15, though the SP v3 model read on 2026-11-09 still lists that v3 version. (B13)
+
+## Recommendations
+
+- Amazon's bid, budget and targeting recommendations are dated estimates refreshed about daily. (B36)
+- Applying one is the same write to the named campaign, keyword or placement that any other change uses. (B36)
+- The cross-product v1 Recommendations API (August 2026) serves the types its *Recommendation types* page, https://advertising.amazon.com/API/docs/en-us/guides/recommendations/recommendations-api/recommendation-types, lists; Amazon adds types over time, and its guide tells readers to tolerate `recommendationType` values they do not recognise. (B36)
+- A v1 recommendation carries a `state` (`ACTIVE`, `APPLIED`, `DEFERRED`, `DISMISSED`, `EXPIRED`, `INACTIVE`) and `potentialImpacts`, "Estimated customer benefits if recommendation is followed". (B36)
+- The three recommendation surfaces (product-specific recommendations, the recommendation list and apply operations, and the v1 recommendations query) have different shapes. (B36)
+
+## Changes Amazon makes itself
+
+- Amazon changes a seller's bids, budgets, targets and creative without a seller write, through its own switches on the campaign, portfolio or ad extension. (B35)
+- For Alexa for Shopping, Alexa+ and prompts, it does so through automatic eligibility with no documented campaign switch. (B35)
+- Auto targeting, keyword groups, SB theme targeting, SB cost-control rules and the v1 `autoCreateTargets` flag choose and refresh targets. (B35)
+- Every SP campaign in the marketplaces Amazon's *Auto-assembled videos* guide, https://advertising.amazon.com/API/docs/en-us/guides/sponsored-products/auto-assembled-videos, covers is opted in to auto-assembled videos; the opt-out, `optOuts.videoExtension`, leaves videos already delivering running until paused through the ad extension. (B35)
+- Campaigns were "automatically enrolled in prompts". (B35)
+- SB headlines can be rewritten under DCO consent. (B35)
+- Full-Funnel, DVA+ and Amazon's creative tools hand planning, targeting or creative to Amazon. (B35)
+
+## Amazon Ads Agent and Seller Assistant
+
+- From 2026-09-29, Amazon Ads Agent is the name of Amazon's unified ad platform holding sponsored ads, Display, Video and Audio and Full-Funnel Campaigns. (B37)
+- Inside it, a closed-beta chat proposes keyword, bid and budget changes and applies them after the advertiser approves, with no public API. (B37)
+- The help centre's "formerly known as Amazon DSP" is the same platform name written into DSP passages. (B37)
+- Seller Central's Seller Assistant (Project Amelia in its 2024 beta, agentic from September 2025) checks whether each product's listing and inventory are ready to advertise, and drafts SP and SB campaigns the seller approves. (B38)
+- Amazon describes an SP auto-optimization, switched on in campaign settings and dated to January 2027 in the US, that expands product targeting, adds relevant keywords and pauses underperforming ones, and holds every bid under a seller-set maximum, with actions the advertiser can edit or reverse at any time. (B38)
+- No page states its thresholds or anything on source negatives, and on 2026-11-09 no Ads API release note or model field documents it or Seller Assistant. (B38)
+- The change history API does not record who made a change. (B38)
+- Seller Assistant workflows run "even when the seller isn't logged in", the seller choosing per workflow whether it surfaces recommendations or takes actions, which are reviewed and approved before they are carried out and logged in an audit trail. (B38)
+- Amazon's examples of those workflows are pricing, restocking, listings and account health, not ads. (B38)
+
+## Outside bid tools
+
+- Third-party bid tools set each target's bid from its value per click times a target ACoS (Ad Badger and AdLabs: revenue per click, order value × conversion rate) on a daily or hourly schedule, and write it through the same Ads API endpoints. (B39)
+- They state that they add negatives from wasted spend, cut bids and pause by hour, pause and revive targets and tie bids to organic rank, none of which Amazon's documented rules do. (B39)
+- Auto-to-manual harvesting is offered both by these tools and by Amazon's target promotion groups. (B39)
+- As their pages read on 2026-11-09, naming no marketplace, Helium 10, Intentwise, Ad Badger and Adbrew sold MCP connections or Claude skills, alongside Amazon's own MCP server. (B39)
+- Pacvue describes "approval-based execution with defined guardrails" and dayparting from Marketing Stream data and 14-day hourly patterns. (B39)
+- Skai describes daily bid and budget optimizations, negatives and harvesting automated on user conditions, and outside agents' bid and budget changes each subject to human approval. (B39)
+
+## Amazon's lift figures
+
+- Amazon's published lift figures for its own automation are vendor-reported comparisons from beta or internal data, with no randomised holdout described. (B40)
+- The Ads Agent figures are "Based on beta estimates", and Sponsored Brands DCO's "up to 1.6% CTR lift" is "Based on internal testing". (B40)
+- Full-Funnel's "67% higher Long-Term ROAS" is "against the blended average of other campaign performance across beta advertisers", and the creative-tool gains are "versus their results before adopting the suite". (B40)
+- The auto-optimization, ads data manager and prompt figures compare adopters or clickers with those who did not. (B40)
+- Improvado's Ivo Petrovic reads the Full-Funnel figure as "not a holdout test on your account". (B40)
+- In an auction, a gain measured on a few early adopters can overstate the gain once many use the same automation. (B40)
+- Baidu's AiAds authors expected its advantage to "gradually abate", and Blake and Coey found naive estimates ignoring test-control interference "exaggerate the treatment's effectiveness by about a factor of 2". (B40)

package/skills/ads-bids-and-budgets/references/bidding.md

@@ -0,0 +1,86 @@
+# Bidding strategies and adjustments
+
+## Sponsored Products strategies
+
+- Sponsored Products has four bidding strategies, in the 3.0 API `LEGACY_FOR_SALES` (dynamic down only), `AUTO_FOR_SALES` (up and down), `MANUAL` (fixed) and `RULE_BASED`. (B5)
+- A campaign created through the API with no strategy gets `LEGACY_FOR_SALES`. (B5)
+- Down only may lower a bid by up to 100% for clicks Amazon judges less likely to convert, and never raises it. (B5)
+- Fixed uses the exact bid plus placement adjustments with no dynamic bidding, which Amazon says may give more impressions but fewer conversions for the spend. (B5)
+- Under up and down, Amazon's current help, library guide and SP 3.0 and v1 models say Amazon may raise or lower a bid by up to 100% for all placements, while the author-facing guide still gives 100% for top of search and 50% elsewhere; no page dates a change. (B6)
+
+## Placement adjustments
+
+- SP placement adjustments raise a bid 0–900% for top of search (up to the first five positions of the top row on desktop, four on mobile), rest of search, product pages and Amazon Business. (B7)
+- An adjustment applies only when the ad competes for that placement. (B7)
+- Dynamic bidding works on the placement-adjusted bid, so a $1 bid with +50% top of search can reach $3 under up and down. (B7)
+
+## Audiences
+
+- In Sponsored Products, adjustments of different kinds multiply (placement × audience × video). (B8)
+- An SP 3.0 campaign may boost up to 10 audiences (Amazon or AMC audiences), each 0–900%; a marketplace can allow fewer, and Amazon's *Adjust Sponsored Products bids* and *Bidding strategies for Sponsored Products* help pages, https://advertising.amazon.com/help/GYYZVM7LGSRYGWV5 and https://advertising.amazon.com/help/GCU2BUWJH2W3A8Z7, give the count where it does. (B8)
+- When a shopper is in several boosted audiences only the highest boost applies, ties going to one audience at random. (B8)
+- In v1 the field `bidAdjustments.audienceBidAdjustments[]` takes at most one per campaign. (B8)
+- Audience ids come from the targetable-entities list, and "Only the audiences retrieved using these filters are usable". (B8)
+- A Sponsored Brands campaign takes one audience group, Amazon-built or AMC, not both. (B8)
+
+## Off-Amazon placements and site restrictions
+
+- SP off-Amazon placements are on by default and use the campaign's own bid and budget. (B9)
+- They take no top-of-search, rest-of-search or product-page adjustments, while dynamic and rule-based bidding still apply. (B9)
+- Amazon bids them on third-party sites by predicted click-through and conversion and submits them to the publisher, who decides which ads show. (B9)
+- `offAmazonBudgetControlStrategy` governs them: `MAXIMIZE_REACH`, the console default, or `MINIMIZE_SPEND`. (B9)
+- Their cost shows in the placement report and, since 2026-06-08, in a US bulksheet column, not in Campaign Manager. (B9)
+- PPC Land's Luis Rijo reports that from 2026-08-10 SP ads may also serve through Amazon Influencer Program creators, enrolled by default at existing bids and budgets. (B9)
+- The placement report itself is in ../ads-review/references/reports.md.
+- A site restriction (Amazon Business only, or Amazon Haul in the marketplaces Amazon's *Sites selection for Sponsored Ads campaigns* help page, https://advertising.amazon.com/help/GJGYD2FKNF3MUWBQ, names) is set at creation, cannot be changed and has its own program-eligibility reason. (B10)
+- A site-restricted campaign has no audience (shopper-cohort) bid adjustments and no Amazon Business placement adjustment. (B10)
+
+## Rule-based bidding
+
+- Rule-based bidding adjusts base bids per impression toward a ROAS guardrail that Amazon bases on the previous 21 days and does not guarantee. (B11)
+- It can raise a bid up to five times the adjusted bid, and sets a goal itself when none is given. (B11)
+- Amazon warns that it can reduce conversions under an aggressive guardrail. (B11)
+- It needs a campaign running at least 10 days with at least 10 conversions in the last 30, at or above the marketplace's minimum daily budget, which Amazon's *Sponsored Products Rule-based bidding overview* guide, https://advertising.amazon.com/API/docs/en-us/guides/rules/bidding-rules/overview, gives per marketplace, so a newly launched campaign is not eligible. (B11)
+- A comparison of rule-based campaigns with ineligible ones mixes the rule's effect with that gate. (B11)
+- Amazon switches it off when 20-day ROAS falls below 30% of the prior 20-to-40-day ROAS, restoring the earlier strategy and bids. (B11)
+
+## Schedule bid rules
+
+- Schedule bid rules are SP only and only raise bids, by an integer 1–100% of the base bid, for an hour window, weekday, date range or event; which marketplaces have "Recurring Events" and which "Individual Events" is given in Amazon's announcement *Events for schedule bid rules, now available for Sponsored Products advertisers in the advertising console*, https://advertising.amazon.com/resources/whats-new/event-based-bid-rules-for-sponsored-products-advertisers. (B12)
+- Several rules add together and the total adds to the placement adjustment: Amazon's example is $1.00 with top of search +10% and a Monday rule +20% giving $1.30. (B12)
+- A rule change takes effect within 24 hours, and a campaign carries at most 20 rules. (B12)
+- They cannot be applied to a campaign with rule-based bidding active, and go on hold if the campaign switches to rule-based bidding. (B12)
+
+## Sponsored Brands
+
+- In Sponsored Brands only top of search and rest of search can be adjusted, positive adjustments going up to 900% for both (announced 2025-06-19; rest of search was limited to 99% before). (B15)
+- Automated bidding lets Amazon optimize placements below top of search, and in the 4.0 API `bidOptimization: true` makes Amazon ignore `bidAdjustmentsByPlacement`. (B15)
+- New negative SB placement adjustments are not accepted from 2026-06-15, while existing ones keep running with their current settings. (B15)
+- Under the goal "drive page visits" Amazon may raise a bid by up to 300% for an auction and lower it where conversion looks less likely. (B15)
+
+## Cost control and display
+
+- Sponsored Brands and display cost control set a target average CPC, not a maximum: the average may be higher than entered. (B16)
+- With placement or audience adjustments, the highest possible CPC exceeds the target. (B16)
+- In Sponsored Brands, cost control is on automatically, and only available, for the goal "drive page visits". (B16)
+- Under display cost control, bids are set automatically, cannot be edited by hand and come with no suggested bids. (B16)
+- Display may raise a bid up to 300% under any optimization strategy. (B17)
+- The display optimization strategy (reach on vCPM; page visits, conversions or leads on CPC) is fixed at creation. (B17)
+- vCPM charges per 1,000 viewable impressions under the MRC definition. (B17)
+
+## Placement isolation
+
+- Placement isolation is the same exact keyword in a campaign with a low base bid and a high top-of-search adjustment, beside a campaign for the other placements. (B18)
+- The Helium 10 Team (2019), Feedvisor, Perpetua and Ad Badger (2020, 2023) argue for it. (B18)
+- Ad Badger (2023) also says a very low base bid may not enter the auction ("Amazon doesn't quite play along with that idea"). (B18)
+- m19 (2026) advises against one-keyword top-of-search campaigns, naming minimum budgets, cost and management load. (B18)
+- Pacvue's moderate-base-bid argument is known only from search summaries. (B18)
+
+## Strategies and hours in practitioner data
+
+- BidX (Lena Einschütz), in observational data on about 130,000 campaigns in February 2024, found down-only campaigns with the lowest ACOS and better conversion than up and down despite higher CPCs. (B19)
+- BidX found the worst ACOS where down-only campaigns carried a product-page adjustment above 0%. (B19)
+- Perpetua (Stephen Bench-Capon), from six weeks of US SP data in spring 2022, found CPC falling from $1.13 early in the day to $0.84 by its end, which it attributes to advertisers exhausting budgets. (B19)
+- Perpetua found conversion around 20% at a 6–10 am Pacific peak against 6–8% at night, and ACOS of 20–23% by day against 41% in the 11 pm hour. (B19)
+- Clear Ads Agency (George Meressa, 2026) holds that most sellers should not daypart, and treats a 2× best-to-worst-hour conversion gap, 30 days of hourly data and about $20,000 a month in spend as minimums. (B19)
+- Practitioners disagree on the best hours: Perpetua 6–10 am Pacific, Clear Ads 6–10 pm, Kepler's apparel client 4 pm to midnight. (B19)

package/skills/ads-bids-and-budgets/references/budgets.md

@@ -0,0 +1,79 @@
+# Budgets, pacing and budget rules
+
+## The daily budget
+
+- A daily budget is averaged over the calendar month: the month's spend stays within daily budget × days, and the invoice is adjusted for any over-delivery. (B22)
+- A single day may spend up to 100% more, or 25% if the profile opted out, read as `isOptedOutForAverageDailyBudgetIncrease` among the account budget feature flags. (B22)
+- Amazon's library guide still prints 25%. (B22)
+- A mid-month change caps the rest of the month at the new budget × days left. (B22)
+- When a budget changes several times in a day, the highest applies that day and the last from the next day. (B22)
+- A cut below what has been spent today stops spend for the rest of the day. (B22)
+
+## Pacing and running out
+
+- Sponsored-ads budgets "are spent as quickly as possible and not paced", while Display, Video and Audio campaigns are paced to daily and minute-level targets with bids adjusted every few minutes. (B23)
+- An out-of-budget campaign is not eligible to serve until the budget resets at midnight. (B23)
+- Portfolio caps and the SP daily budget cap in Advertising Settings also stop campaigns. (B23)
+- A budget raise "typically" takes 1–2 hours to show as Delivering, and Amazon advises against frequent budget changes within one day. (B23)
+- A campaign that exhausts its budget on an event day pauses until midnight, and Amazon names budget increases and budget rules set in advance as the means to keep it running. (B23)
+- Event days and seasons: ../ads-seasons/SKILL.md.
+
+## Budget types by product
+
+- Sponsored Brands takes a daily or a lifetime budget, and a lifetime budget requires start and end dates. (B24)
+- A live SB campaign cannot switch from daily to lifetime (Amazon's route is to copy it into a new campaign), and a live lifetime budget can only rise. (B24)
+- SP takes daily budgets only. (B24)
+- An SD campaign created through the API without a budget gets a regional default in local currency, which the *Default budgets* section of Amazon's *Limits, constraints, and quotas* page, https://advertising.amazon.com/API/docs/en-us/reference/concepts/limits, gives per marketplace. (B24)
+
+## Budget usage and hourly cost
+
+- Budget usage percent is the day's spend over the day's effective budget, which includes budget-rule increases and the average-daily-budget lift. (B25)
+- It is read as `budgetUsagePercent` with `usageUpdatedTimestamp` from the SP, SB and SD campaign and the portfolio budget usage operations, for up to 100 ids. (B25)
+- Stream v1's `budget-usage` feed (every 5% consumed) needs an SQS or Firehose destination, stops on 2027-06-30 and is "not carried forward in Stream v2", Amazon pointing to the Campaign Management API instead. (B25)
+- Hourly cost per campaign comes from v1 reports with the `hour.value` dimension, kept 14 days with a 14-day maximum range. (B31)
+
+## Budget recommendations
+
+- The SP budget recommendation returns a suggested daily budget, the share of the last 7 days in budget (0 to 1), and lower and upper estimates of missed impressions, clicks and sales that are "not a guarantee". (B26)
+- Amazon suggests waiting until a campaign has been active nine days. (B26)
+- SB and SD have their own budget recommendations; at their launch Amazon said roughly ten percent of SB campaigns went out of budget daily (2023). (B26)
+- The recommended budget is estimated missed clicks × an estimated CPC, the missed clicks coming from a model of similar campaigns that stayed in budget combined with the campaign's own CTR and sales. (B26)
+- The missed sales are click-attributed sales, not sales caused by the ad. (B26)
+- Field experiments on paid search found non-experimental returns overstated. (B26)
+- No published validation against what raised campaigns then did was found, and Amazon's pages do not say whether the model accounts for the hour of the missed traffic. (B26)
+
+## Budget rules
+
+- Budget rules only raise a daily budget, by a percentage, on a schedule (date range, recommended event, weekly days, or hours in the marketplaces Amazon's *Schedule-based rules* guide lists, https://advertising.amazon.com/API/docs/en-us/guides/rules/budget-rules/schedule-based) or on performance. (B27)
+- Performance rules read ACOS, CTR, CVR or ROAS on SP and SD, and ROAS, top-of-search share or new-to-brand on SB, over 7 days for sellers and 14 for vendors. (B27)
+- Several rules add (+40% and +100% apply as +140%), and a campaign can carry up to 250. (B27)
+- The API guide says rules are evaluated at the start of the day and again when a rule is created or updated or the daily budget changes, while the help page describes a daily review that sets the next day's budget. (B27)
+- A performance rule does not apply below a minimum daily budget; Amazon's *Understand budget rules in Sponsored ads* page, https://advertising.amazon.com/help/GNSMLANWNF344YBE, states it for the US in US dollars, and no page read on 2026-11-09 states it for another marketplace. (B27)
+- A raised budget reads back as SP `budget.effectiveBudget`, SB and SD `ruleBasedBudget.value`, or v1 `monetaryBudget.ruleValue`. (B27)
+- Amazon warns that `applicableRuleId` can be incomplete when several rules are active; the campaign's rule list is the full record. (B27)
+
+## Portfolios and the account cap
+
+- A portfolio cap is a date range (`DATE_RANGE`), a monthly recurring amount (`MONTHLY_RECURRING`) or none (`NO_CAP`), and a campaign belongs to at most one portfolio. (B28)
+- Reaching the cap stops the portfolio's campaigns with `PORTFOLIO_OUT_OF_BUDGET`. (B28)
+- With unspent sharing on (`budgetControls.campaignUnspentBudgetSharing`), a campaign that has spent its own daily budget can use other campaigns' leftovers from earlier days in the month, "up to 100% more than their average daily budget on any given day", while the portfolio's month stays within the sum of daily budgets × days. (B28)
+- Sharing is set per portfolio, and is on by default for portfolios created after 2025-06-20. (B28)
+- The SP account daily budget cap is a seller-only console setting over all SP campaigns, with no API operation found. (B29)
+
+## Practitioners and tools
+
+- Trellis (Mike Lepine) advises recording the time each campaign ran out of budget; its Monthly Spend Pacer projects from month-to-date plus a 7-day run rate and acts only outside a 10% band. (B33)
+- Intentwise (Michael Waters) observes that advertisers commonly exhaust budgets by the evening and that CPCs are lower at night. (B33)
+- m19 rewrites campaign and portfolio caps daily, spends up to 2× its daily target on a day and 1.1× its monthly target, and asks sellers not to edit budgets in the console. (B33)
+- Helium 10's Budget Manager adjusts daily budgets toward monthly and annual plans, pauses campaigns at the plan's cap and does not consider portfolio caps. (B33)
+- SmartScout describes Pacvue's budget tool as taking monthly caps for a fiscal year. (B33)
+- Skai moves budget between a portfolio's campaigns to a budget and KPI plan. (B33)
+- Perpetua's Monthly Budget Tracker projects month-end spend and enforces nothing. (B33)
+- Kepler reports one apparel client's daily serving rising from 8.5 to 16.5 hours, with ROAS up 95% and CPC down 58%, after early-day bid cuts with Pacvue, a single-client before/after without a control. (B33)
+
+## Research on budgets
+
+- Research on budget-constrained bidding finds adaptive pacing, which adjusts bids to the advertiser's own spend path, asymptotically optimal, and serving greedily until the budget ends suboptimal when budgets are finite. (B34)
+- It finds that each budget-management method used market-wide leads to a different equilibrium. (B34)
+- It notes that a budget that runs out ends a campaign's observed path, so "what if it had not run out" is a counterfactual simulation. (B34)
+- It notes that spend-response estimates become more uncertain for reallocations far outside the spend levels in the history. (B34)

package/skills/ads-bids-and-budgets/references/writes.md

@@ -0,0 +1,30 @@
+# Writing bids and budgets
+
+Paths, headers, origins, the token and the reply's handling are the amazon-ads skill's references/door.md.
+
+## Bid limits
+
+- Amazon publishes minimum and maximum SP, SB and SD bids per marketplace and currency on the Ads API *Limits, constraints, and quotas* page, https://advertising.amazon.com/API/docs/en-us/reference/concepts/limits. (B14)
+- On 2026-11-09 that page contained at least one apparent error (EG SP maximum 5.50). (B14)
+- A refused SP 3.0 bid carries a `biddingError` with its reason and the marketplace's `lowerLimit` and `upperLimit`. (B14, B20)
+
+## Bid writes
+
+- In SP 3.0, bids are written through the keyword, target and ad group updates, and strategy, placement and audience adjustments through the campaign update, up to 1,000 per call. (B20)
+- An SP 3.0 bid write answers 207 with per-index errors. (B20)
+- In v1, bids are written through the target, ad group and campaign update operations, under per-product ceilings: SP 1,000; SB 10 campaigns or ad groups and 1,000 targets; SD 100 campaigns or ad groups and 1,000 targets. (B20)
+- In SB, bids are written through the keyword and target updates, 100 per call, and placement and audience adjustments through the v4 campaign update, 10 per call. (B20)
+- An SB keyword or target bid is mutable only when its campaign has no enabled optimization rule. (B20)
+- In SD, bids are written through the target and ad group updates; an optimization rule on the ad group overrides manual target bids, and under display cost control "Bids can’t be manually edited". (B20)
+- Amazon's v1 overview lists SD as supported and publishes an SD v1 model with update operations, with no dated GA note. (B20)
+
+## Budget writes
+
+- In v1, a budget's `recurrenceTimePeriod` is `DAILY`, `LIFETIME` or `MONTHLY`. (B30)
+- A global SP campaign carries a separate budget per marketplace, in local currency, in `marketplaceSettings`. (B30)
+- Budgets are in the marketplace's currency, and Amazon refuses a budget outside the marketplace's range, below the campaign's bids or in a mismatched currency, naming the reason in the error. (B30)
+- In SB, budget amounts are written through the v4 campaign update, 1–10 per call, where `budgetType` is accepted at create only. (B32)
+- In SD v3, budget amounts are written through the campaign update, at most 100 per call, where `budgetType` is `daily` only and the 207 reply does not carry the new budget. (B32)
+- The SD v1 update-budget schema lacks the `recurrenceTimePeriod` the read model requires. (B32)
+- Developers report an SD v1 budget update without `recurrenceTimePeriod` returning 207 with no error while the budget is unchanged (issue 475, open with no Amazon reply on 2026-11-09). (B32)
+- Developers also report an SP prompt-extension pause reverting by the next day, and a required `statusMessage` missing from the v1 advertiser-accounts query. (B32)

package/skills/ads-change/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ads-change
+description: "What a change to a seller's sponsored ads leaves behind and how its effect can be read: Amazon's change history and its gaps, write replies and refusals, the tests Amazon offers and lacks, practitioners' and vendors' methods, and what research finds about before/after, bids, positions, holdouts and switchbacks. For changing sponsored ads or judging whether an ad change worked."
+---
+
+## Change history
+
+- Amazon's change history returns up to 90 days of change events for SP and SB campaigns, each with its `entityType`, old and new values and timestamp; not Sponsored Display's, nor who made them (C1, C2).
+- It has no event for negative product targets, audience or shopper bid adjustments, ad creative or budget-rule associations (C2).
+- No history, reply or report field records a change's reason, expected effect, judging metric or windows (C6).
+
+## Writes
+
+- Writes answer HTTP 207, each item's status in the body; v1's `partialSuccess` is written with some fields refused (C3).
+- No v1, SP v3, SB v3, SB v4, SD v3 or Portfolios write takes an idempotency key; creates share no transaction; a chain stopped part-way shows `CAMPAIGN_INCOMPLETE` or `AD_GROUP_INCOMPLETE` (C3).
+- A seller's campaign create reusing a campaign name is refused (C4).
+- Some edits to entities Amazon created automatically are refused (C5).
+
+## Testing
+
+- No Amazon page or model read offers a randomized test for sponsored ads; Manage Your Experiments covers listing content only (C10).
+- Amazon recommends limiting changes while testing bidding strategies, to attribute a difference to a specific change, and reviewing bids about once every two weeks (C9).
+- Practitioners disagree on how long to wait after a bid change (C20).
+
+## Before and after
+
+- Across 25 large ad field experiments the median ROI confidence interval exceeded 100 percentage points (C13).
+- Position differences won by bidding carry selection bias that randomizing one advertiser's bids cannot eliminate (C14).
+- A report shows outcomes only at the bid that ran (C27).
+- A campaign picked after an extreme period shows a change that is partly regression to the mean (C18).
+- Ordinary p-values are unreliable when a test stops on watching its results (C16).
+- `cx-listing-playbook`'s effect review returns held, not held or cannot tell (C19).
+
+## References
+
+- references/history.md: event fields, how far back, `THEME`, missing event types.
+- references/writes.md: 207 replies, idempotency, refusals, target types.
+- references/tests.md: Amazon's advice, missing tests and own experiments, practitioners' waits, vendors.
+- references/findings.md: organic, noise, positions, durability.
+- references/designs.md: ratios, interference, switchbacks, CUPED, verdicts.
+- ../ads-review/references/metrics.md: metric definitions.
+- The amazon-ads skill's references/door.md: paths, headers, the token.

package/skills/ads-change/references/designs.md

@@ -0,0 +1,57 @@
+# Measurement designs
+
+## Ratios
+
+Amazon's derived metrics are computed by aggregating numerator and denominator across rows at the chosen grain and then dividing. (C7)
+
+## Shared budgets and auctions
+
+When test and control arms share budgets or auctions, a measured bid effect can be "severely biased" unless each arm keeps a separate budget. (C15)
+In an Airbnb pricing meta-experiment, at least 20% of the individual-randomized estimate was interference bias, which cluster randomization removed. (C15)
+In simulation, blocked cluster randomization cut the naive bias by as much as 62%, at the cost of higher variance. (C15)
+Wager and Xu estimate marginal responses with ±1 randomized shocks per unit while staying at a fixed market equilibrium. (C15)
+
+## Switchbacks
+
+Amazon's pricing scientists, unable to split shoppers for a price test, run switchbacks over time, report that random-days switchbacks cut standard error by 60%, and name carryover through recommendations. (C23)
+Amazon-authored work on advertiser experiments states that auction competition between treated and control advertisers biases simple advertiser randomisation. (C23)
+Bojinov, Simchi-Levi and Zhao set optimal switchback assignment under carryover of order *m*, with the Horvitz-Thompson estimator unbiased for lag *p* ≥ *m*, and suggest periods shorter than the carryover. (C23)
+Hershaff, a seller, reports (Substack, 2026-02-13) that a month-long daily ad on/off switchback gave an incremental ROAS of 1.25 on total sales against platform ROAS near 2.35, rising to 1.54 with an MMM-estimated adstock. (C23)
+Hershaff calls 1.25 a floor, because a daily switchback assumes no carryover. (C23)
+
+## Staggered changes
+
+With treatment at different times, the two-way fixed-effects estimator equals a weighted average of all two-group/two-period comparisons with weights that may be negative, so its coefficient can be negative while every effect is positive. (C24)
+In event studies, apparent pretrends can arise solely from effect heterogeneity. (C24)
+A staggered difference-in-differences is unbiased for a weighted average effect under random assignment of the adoption date. (C24)
+With a treatment of varying dose, parallel trends does not rule out selection bias across doses. (C24)
+
+## Synthetic control
+
+Abadie's conditions for a synthetic control are an effect large against the outcome's volatility, donors that did not adopt similar changes, no anticipation, no interference and a close pre-period fit, with inference by placebo reassignment. (C25)
+
+## Variance and checks
+
+CUPED cuts the variance of a treatment-control difference to var(Y)(1−ρ²) with a pre-period covariate, about 50% on Bing. (C26)
+The same metric over 1–2 pre-period weeks "works well", and "Never use covariates that could be affected by the treatment". (C26)
+A sample ratio mismatch between arms, detected by a chi-square test, implies a selection bias that invalidates the results most of the time. (C26)
+Carryover from earlier experiments on the same units lasted more than three weeks at Bing and was detected with A/A tests. (C26)
+
+## Many tests
+
+Across many tests, a step-up procedure controls the false discovery rate (the expected share of falsely rejected hypotheses) for independent tests. (C28)
+Multilevel models instead shrink estimates toward each other. (C28)
+Winners chosen from a group of experiments carry a selection bias, for which Lee and Shen give a correction. (C28)
+An objective Bayesian prior needs historical A/B data; Bing's was built from thousands of experiments. (C28)
+With fat-tailed effects, a lean strategy of more ideas on smaller samples is preferred. (C28)
+
+## Intent-to-treat
+
+Intent-to-treat compares whole groups and stays valid but less precise. (C29)
+Public-service-ad control experiments are invalid when delivery algorithms optimise for performance. (C29)
+
+## The listing playbook's verdicts
+
+In `cx-listing-playbook`'s effect review, *held* means the targeted metric moved, after the control's movement is taken out, in the expected direction by at least the smallest move logged before the change, with orders not falling and no confounder or event explaining it. (C19)
+*Not held* means the window held enough data to have seen that move and did not, or the metric moved the wrong way. (C19)
+*Cannot tell* is every other case. (C19)

package/skills/ads-change/references/findings.md

@@ -0,0 +1,32 @@
+# What research finds about ad effects
+
+## Sponsored search and organic listings
+
+A platform experiment that blocked sponsored search for 3% of an e-commerce site's visitors found that sponsored search "steals business from organic listings" and reduced total transactions. (C12)
+A marketplace study found shoppers preferring top-ranked organic listings to sponsored listings of the same product and position. (C12)
+
+## Noise
+
+Across 25 large ad field experiments the median confidence interval on ROI was over 100 percentage points wide, because individual sales are highly variable relative to advertising's effect. (C13)
+Across 15 Facebook experiments, observational methods "often fail to produce the same effects as the randomized experiments". (C13)
+Ordinary p-values and intervals are unreliable when a test is stopped on watching its results. (C16)
+
+## Positions and bids
+
+Outcome differences between ad positions won by bidding are biased by selection, which "cannot be eliminated by randomizing the bids for the focal advertiser" because competitors bid too. (C14)
+Narayanan and Kalyanam's regression discontinuity finds naive estimates overstate position effects, which are "much smaller" and "exist only in some of the positions". (C14)
+In Narayanan and Kalyanam's study, position effects are weaker when the phrase carries brand or product information, and larger for smaller advertisers and less experienced consumers. (C14)
+Agarwal, Hosanagar and Smith find profit can be higher below the top position. (C14)
+The four studies of conversion by position disagree. (C14)
+A report shows what happened at the bid that ran, never what a target would have done at another bid. (C27)
+Amazon's AuctionGym authors state that "an advertiser does not observe counterfactual outcomes of bid amounts that were not submitted", and that competitors' adaptation complicates evaluating bidding strategies from logged data alone. (C27)
+
+## Short term and long term
+
+Short-term ad effects are "not always predictive of the long-term effect". (C17)
+User learning about ads took months to develop on Google search, and an ad shutoff for a mobile game reduced organic installs by 20–30% through store rankings. (C17)
+
+## Regression to the mean
+
+Units picked because their last measurement was extreme tend to move back toward their mean with no intervention. (C18)
+So a campaign handed to automation after an unusually good or bad period shows a change that is partly regression to the mean. (C18)

package/skills/ads-change/references/history.md

@@ -0,0 +1,21 @@
+# Change history
+
+## What it returns
+
+Amazon's change history returns up to 90 days of change events for Sponsored Products and Sponsored Brands campaigns, each with its previous value, new value and Unix timestamp. (C1)
+For a campaign, its change types include STATUS, IN_BUDGET, BUDGET_AMOUNT, END_DATE, SMART_BIDDING_STRATEGY and PLACEMENT_GROUP. (C1)
+Amazon's model states "Changes for Sponsored Display campaigns are not returned", and that the history "doesn't return information about who made the change". (C1)
+
+## An event
+
+An event carries `entityType`, `entityId`, `changeType`, string `previousValue` and `newValue`, a UTC epoch `timestamp` and `metadata`. (C2)
+The history's earliest date reaches back as far as the model states: 90 days on 2026-11-09. (C2)
+`THEME` events need the history's v1.1 response; without it the call answers 400. (C2)
+The history's bidding-strategy and placement enums differ from Sponsored Products 3.0's. (C2)
+It has no event type for negative product targets, audience or shopper bid adjustments, ad creative or budget-rule associations. (C2)
+
+## What no field records
+
+No field in Amazon's change history, write replies or report rows records a change's reason, expected effect, judging metric or windows. (C6)
+
+How the call is made: the amazon-ads skill's references/door.md.

package/skills/ads-change/references/tests.md

@@ -0,0 +1,42 @@
+# Tests: Amazon's, practitioners' and vendors'
+
+## Amazon's guidance
+
+Amazon recommends limiting changes while testing bidding strategies, so that a difference in performance can be attributed to a specific change. (C9)
+Amazon recommends reviewing bids "about once every two weeks", and judging a negative keyword "after it has received at least 20 clicks" and after "two weeks or more". (C9)
+No Amazon page read states a statistical test or confidence level for an ad change. (C9)
+
+## No randomized test for sponsored ads
+
+No Amazon page or model read offers a randomized test for sponsored ads. (C10)
+Manage Your Experiments covers listing content only: images, titles, bullets, descriptions and A+. (C10)
+Brand Lift surveys exposed and unexposed groups, excludes SP, and its API operations sit under DSP; the Brand Lift operations its launch page names are in no model. (C10)
+Creative Testing is a pre-launch DSP panel survey, and SalesDuo's Borle (2026) agrees. (C10)
+SB v4 lets several ads share an ad group, with no stated split. (C10)
+DSP alone has ten 10% customer holdout groups, on a page that advises against before/after comparison of bid adjustments. (C10)
+Multi-touch attribution divides credit; the marketplaces where it is available, and whether it is still a beta, are stated on Amazon's page *Uncover ad value across the funnel with multi-touch attribution (beta)*, https://advertising.amazon.com/resources/whats-new/uncover-ad-value-across-funnel-with-multi-touch-attribution; AMC's exposed against non-exposed conversions are an observational split; MMM feeds a model the advertiser runs. (C10)
+No Ads API model or release note read has an experiment, split or holdout operation, and no page read offers sellers a self-serve SP incrementality measurement. (C10)
+
+## Amazon's own experiments
+
+Amazon states it is "continually experimenting to refine and improve our ad auctions", including "introducing, removing, or modifying the data points or factors used in the auction process". (C22)
+Amazon-authored product-search papers report online A/B tests on 50 million and 140 million queries, and a ranking change serving customers since 2025. (C22)
+Amazon reports that 80% of bid changes on clicked SP search ads came within one day of a prior change (2019–2024). (C22)
+Amazon reports that in one study competitors' average bids on keywords an advertiser stopped bidding on dropped about 83%, from $15.96 to $2.74. (C22)
+
+## Practitioners
+
+Practitioners disagree on how long to wait after a bid change: Ad Badger's automated bidder typically a 24-hour window, Ad Badger's blog at least seven days, Pare's George Reid 7–14 days, and BidX's Selina Krüger the seventh day after the observation period when the gap to target ACoS is small. (C20)
+Ad Badger's August 2026 attribution article states a 14-day SP window and order-date reporting, which Amazon's v1 overview contradicts. (C20)
+Eva Commerce's Hai Mag proposes a geo holdout for branded SP, though the v1 model gives SP no location target. (C20)
+Hai Mag says 80–90% of branded-ad traffic and sales return organically when the ad is removed, without a source. (C20)
+Perpetua measures category-term incrementality with Total ACoS. (C20)
+Seller Labs says conversion "swings on single orders" below a few hundred sessions a month and uses 60- or 90-day windows or skips such ASINs, where Amazon's targeting guide gives 20 clicks for judging a negative. (C20)
+
+## Vendors, in their own words
+
+Skai calls holdout testing the "gold standard" and computes iROAS as incrementality score × ROAS. (C21)
+Pacvue describes its iROAS as using "multiple advanced linear regression data models". (C21)
+Intentwise calls its What Changed comparison "the starting point". (C21)
+Teikametrics states it updates Amazon bids "Hourly". (C21)
+Helium 10's change log labels a change's source, including "In Seller Central or 3rd party". (C21)

package/skills/ads-change/references/writes.md

@@ -0,0 +1,28 @@
+# Write replies and refusals
+
+## The 207 reply
+
+Writes answer HTTP 207, and Amazon states: "Applications must parse the response body to determine the status of each individual operation". (C3)
+Ads API v1 returns `success`, `partialSuccess` and `error`, keyed by request index; a `partialSuccess` item was written with some fields refused and carries its errors, and a success carries `lastUpdatedDateTime`. (C3)
+Sponsored Products 3.0 returns per-item `success` and `error` matched by `index`, its objects carrying `extendedData.lastUpdateDateTime`. (C3)
+
+## No idempotency, no transaction
+
+No create, update or delete in v1, SP v3, SB v3, SB v4, SD v3 or Portfolios takes an idempotency key; Amazon's models carry them only for DSP audiences, AMC custom models and billing. (C3)
+Creates share no transaction, so a chain can stop part-way and leave a campaign with no ad group or an ad group with no ad. (C3)
+The API reports those as `CAMPAIGN_INCOMPLETE` and `AD_GROUP_INCOMPLETE`. (C3)
+
+## Names
+
+Amazon states: "Sellers aren't allowed to have duplicate campaign names, but vendors can". (C4)
+A seller's repeated campaign create with the same name is refused, with `NAME_NOT_UNIQUE` in SP 3.0 and `FIELD_VALUE_NOT_UNIQUE` in v1. (C4)
+Ad group names are unique only within a campaign. (C4)
+
+## Entities Amazon created
+
+Entities Amazon created automatically, such as an auto campaign's targeting clauses, are refused for some edits. (C5)
+The refusals read `AUTOCREATED_ENTITY_CANNOT_EDIT` in v1 and `AUTO_TARGETING_CLAUSE_CANNOT_BE_ARCHIVED_MANUALLY` in SP v3. (C5)
+
+## Target types
+
+In the v1 model, SP and SB targets are keyword, product, category and theme targets, with no location, daypart, device or audience target; those are DSP-only. (C8)