amazon-ads-manager#

Amazon Advertising API wrapper for live campaign management — read performance reports, update bids, pause keywords, add negatives.

Setup (one-time)#

Create a .env file in the skill root directory (same level as this SKILL.md):

text

AMAZON_ADS_CLIENT_ID=amzn1.application-oa2-client.xxx
AMAZON_ADS_CLIENT_SECRET=xxx
AMAZON_ADS_REFRESH_TOKEN=Atzr|xxx
AMAZON_ADS_PROFILE_ID=          # find via `ads.py profiles`
AMAZON_ADS_REGION=NA            # NA | EU | FE

How to get credentials:

1. Amazon Ads Developer Console → create app → get client_id + client_secret
2. OAuth flow → get refresh_token (login with your Seller Central account)
3. Run ads.py profiles to find your AMAZON_ADS_PROFILE_ID (one per marketplace)

If credentials are not yet configured: ask the skill owner (the person who installed this skill) to provide the Amazon Ads API credentials and save them to the .env file listed above. Without these, all commands will fail with a clear error message listing exactly which variables are missing.

---

Commands#

List profiles (find your PROFILE_ID)#

bash

uv run <skill-dir>/scripts/ads.py profiles

Returns all linked ad accounts with profileId, marketplace, currency. Set AMAZON_ADS_PROFILE_ID to the correct profileId for subsequent calls.

---

View campaigns#

bash

# Active campaigns
uv run ... campaigns

# All (including paused)
uv run ... campaigns --state all

Returns: campaignId, name, state, budget, bidding strategy.

---

View ad groups#

bash

uv run ... adgroups <campaign_id>

View keywords#

bash

uv run ... keywords <adgroup_id>

Returns: keywordId, keywordText, matchType, state, bid.

---

Performance reports (async, ~30–90 sec)#

bash

# Campaign-level ACOS/ROAS summary (last 30 days)
uv run ... report campaigns --days 30

# Keyword-level performance
uv run ... report keywords --days 30

# Search terms (harvesting + negation)
uv run ... report searchterms --days 30

# Scope to one campaign
uv run ... report keywords --days 30 --campaign-id 12345678

Output fields (enriched): impressions, clicks, cost, attributedSales7d, attributedUnitsOrdered7d, acos_pct, roas, ctr_pct, cpc

Sorted by spend descending.

---

Update keyword bid#

bash

uv run ... set-bid <keyword_id> <new_bid>
# e.g.
uv run ... set-bid 987654321 0.85

Pause / enable / archive keyword#

bash

uv run ... set-state <keyword_id> paused
uv run ... set-state <keyword_id> enabled

Add campaign-level negative keyword#

bash

# Negative exact (default)
uv run ... add-negative <campaign_id> "bad search term"

# Negative phrase
uv run ... add-negative <campaign_id> "irrelevant" --match phrase

---

Optimization Workflow#

Step 1 — Get overview#

bash

uv run ... report campaigns --days 30

Flag campaigns with acos_pct > 50% for drill-down.

Step 2 — Drill into problem campaigns#

bash

uv run ... report keywords --days 30 --campaign-id <id>

Classify each keyword:

ConditionActionspend > $5, sales = 0, clicks ≥ 10🔴 Pause — pure wasteacos_pct > target × 1.5, clicks ≥ 20🟠 Reduce bid by 20–30%acos_pct > 0, acos_pct < target, impressions < 500🟡 Raise bid by 20%ctr_pct > 0.5%, orders/clicks < 5%🟡 Listing problem — don't touch bidimpressions = 0Check match type / bid floor

Target ACOS benchmarks: SP Manual 25–35% · SP Auto 35–45% · SB 40–55%

Step 3 — Harvest search terms#

bash

uv run ... report searchterms --days 30

From auto campaigns:

• acos_pct < target AND clicks ≥ 5 AND sales > 0 → add to manual exact at 80% of current auto bid
• spend > $3 AND sales = 0 AND clicks ≥ 8 → add as negative exact

Step 4 — Execute changes#

For each action identified, run the appropriate command ( set-bid, set-state, add-negative). Present a summary of what was changed and the expected impact.

---

Output Format#

After analysis, present:

text

## 广告优化报告

### 账户概览 (最近 N 天)
| 总花费 | 总销售额 | ACOS | ROAS | 点击数 | 平均 CPC |
|--------|---------|------|------|--------|---------|

### 🔴 高优先级 — 建议暂停 (X 个词，节省 $X/月)
| Campaign | Ad Group | Keyword | 花费 | 点击 | 销售 | 操作 |

### 🟠 降价建议 (X 个词)
| Keyword | 当前 bid | 建议 bid | 当前 ACOS | 目标 ACOS |

### 🟢 收割词 — 建议加入 Manual (X 个词)
| 搜索词 | Auto 花费 | ACOS | 建议 bid |

### 执行摘要
已执行 / 等待确认 X 项操作

Always ask for confirmation before executing bid changes or pauses unless the user explicitly said "直接执行" or "just do it".