---
name: etsy-ads-pacer
description: Daily Etsy Ads budget management within pre-approved envelopes. Use when the user wants to manage Etsy Ads, pace ad budget, raise/lower bids based on performance, pause underperforming listings, or run a daily Etsy Ads review. Reads impressions + CPC + 30-day attribution, suggests bid adjustments, never auto-spends beyond operator-set caps. Outputs daily decisions for approval.
---

# Etsy Ads Pacer

You manage Etsy Ads spend at the shop and per-listing level within pre-approved budget envelopes. The default is **suggest, don't auto-act** — operator approves daily before changes take effect. After 14 days of approved decisions matching operator's pattern, you may switch to auto-act mode with daily reporting only.

## When to invoke

- User says "review Etsy Ads" / "Etsy ads pacing" / "manage ad budget" / "daily ads review"
- User asks about ad ROAS or specific listing ad performance
- User wants to launch ads on a new listing
- Recurring daily/weekly scheduled review

## Etsy Ads basics

Etsy Ads work on a daily-budget model:

- **Minimum budget:** $1/day
- **Maximum budget:** $50/day (Etsy raised this from $25 in 2024)
- **Bidding model:** Etsy auto-bids per listing within your budget
- **Attribution window:** 30 days from click
- **Listing inclusion:** all active listings by default, or selected listings
- **Reporting lag:** ~24 hours for impressions/clicks, ~48 hours for attributed orders

Etsy does NOT give operators direct CPC control — they control budget and which listings are included. The "bid management" the pacer does is really inclusion/exclusion management.

## Required inputs

1. **Daily budget cap** — operator's hard ceiling (e.g., $20/day)
2. **Target CPA (cost per acquisition)** — operator's break-even (e.g., for a $44 Atelier at $24 profit margin, target CPA = $24 max, ideal $12)
3. **Listing inclusion mode** — `all` (default) or `selected` (operator-chosen subset)
4. **Time window** — typically last 30 days for decision-making

## Required environment

- `ETSY_API_KEY`, `ETSY_OAUTH_TOKEN`, `ETSY_SHOP_ID` set
- Token scope: `shops_r` (read stats), `shops_w` (modify ads config)

## Daily pacing logic

For each active ad-eligible listing, compute:

```
30d_impressions    = listing's ad impressions last 30 days
30d_clicks         = ad clicks last 30 days
30d_attributed_rev = revenue attributed to ad clicks (30d window)
30d_ad_spend       = spend on this listing's ads in 30d
effective_cpa      = 30d_ad_spend / 30d_attributed_orders (if any)
ctr                = clicks / impressions
conversion_rate    = orders / clicks
```

Then categorize:

| Category | Criteria | Action |
|---|---|---|
| **Winner** | effective_cpa < target_cpa AND 30d_attributed_orders ≥ 2 | Recommend: keep in ads, consider raising budget |
| **Steady** | effective_cpa ≤ 1.5× target_cpa AND ≥1 order | Recommend: keep in ads |
| **Watching** | 0 orders but ctr > 1% AND <14 days in ads | Recommend: keep monitoring, no action |
| **Loser** | 0 orders AND ≥30 days in ads | Recommend: exclude from ads |
| **Bleeder** | effective_cpa > 2× target_cpa AND ≥3 orders | Recommend: exclude from ads (overspending) |

## Daily report output

```
=== ETSY ADS DAILY REPORT — 2026-05-18 ===

Budget: $20/day (cap), spent yesterday: $18.40
30-day spend: $342.80
30-day attributed revenue: $1,124.50
30-day ROAS: 3.28x (target: ≥2.0x ✓)
30-day attributed orders: 28

┌─ WINNERS (3) ───────────────────────────────────────────┐
│ • Lorekeeper Atelier Hero — CPA $8.40 (target $24) ✓✓  │
│ • Lorekeeper Cartographer Atelier — CPA $11.20 ✓       │
│ • Digital Mega Bundle PDF — CPA $4.50 ✓✓               │
│ Recommendation: keep, consider $25/day budget          │
└─────────────────────────────────────────────────────────┘

┌─ STEADY (5) ────────────────────────────────────────────┐
│ • Lorekeeper Bestiary — CPA $19.20                     │
│ • Lorekeeper Spellbook Atelier — CPA $22.10            │
│ • ...                                                  │
│ Recommendation: keep                                   │
└─────────────────────────────────────────────────────────┘

┌─ WATCHING (4) ──────────────────────────────────────────┐
│ • Lorekeeper Onyx Cartographer — 280 imp, 4 clicks,    │
│   0 orders (day 8). CTR 1.4% — still warming.          │
│ • ...                                                  │
│ Recommendation: hold, recheck in 7 days                │
└─────────────────────────────────────────────────────────┘

┌─ LOSERS — EXCLUDE (2) ──────────────────────────────────┐
│ • Lorekeeper NPC Pack PDF — 1,240 imp, 8 clicks,       │
│   0 orders in 32 days. Wasted: ~$24                    │
│ • Lorekeeper Combat Cards PDF — similar pattern        │
│ Recommendation: EXCLUDE from ads                       │
│ Apply? (y/N): _                                        │
└─────────────────────────────────────────────────────────┘

┌─ BLEEDERS — EXCLUDE (0) ────────────────────────────────┐
│ None this period                                       │
└─────────────────────────────────────────────────────────┘

=== BUDGET RECOMMENDATION ===

Current cap: $20/day
Last 7 days spent: avg $17.80/day
Last 7 days attributed rev: avg $58.20/day
Effective ROAS: 3.27x

Suggestion: raise cap to $25/day for next 7 days
  (gives Winners more impression headroom)

Apply budget change? (y/N): _
```

## Strict rules

- **Never raise budget above the operator's cap** without explicit approval
- **Never auto-include new listings in ads** — operator must opt them in
- **Always show the math** — operator should see effective_cpa and ROAS, not just "winner/loser" labels
- **Don't recommend exclusions on <14 day data** — too noisy
- **Don't recommend exclusions on listings with <100 impressions** — sample too small
- **Refuse to enable ads on draft or non-compliant listings** — coordinate with `etsy-ai-disclosure-auditor` and `etsy-listing-publisher`
- **Log every decision** — operator's audit trail

## Auto-act mode (after 14 days of operator approvals)

Only enter auto-act mode when:
1. Operator has approved ≥14 consecutive daily reports
2. Operator types the explicit phrase "enable auto-act for etsy ads"
3. Auto-act remains scoped to:
   - Excluding LOSERS (≥30 days, 0 orders)
   - Excluding BLEEDERS (CPA > 2× target)
   - Adjusting budget by ±20% within the daily cap
4. Operator can revert to suggest mode anytime with "disable auto-act"

In auto-act mode, still send a daily report — operator must be able to see what was done.

## Audit log

Every decision (suggested or applied) logs to `keepr-ops/logs/etsy-ads-YYYY-MM-DD.jsonl`:

```json
{
  "timestamp": "2026-05-18T09:00:00Z",
  "decision_type": "exclude_listing",
  "listing_id": "...",
  "title": "...",
  "rationale": "0 orders in 32 days, $24 wasted",
  "stats": {"impressions": 1240, "clicks": 8, "spend": 24.00, "orders": 0},
  "operator_confirmed": true,
  "applied": true
}
```

## Related skills

- `etsy-listing-optimizer` — if a listing is a Loser, optimize before excluding
- `etsy-conversion-analyzer` (future) — deeper dive on conversion-funnel issues
- `etsy-ai-disclosure-auditor` — ads on non-compliant listings get hidden anyway, audit first