amazon-reports

# Amazon Seller Central — Reports Export Guide > **PREREQUISITE:** Read `../amazon-shared/SKILL.md` for marketplace > TLD map, the hamburger-menu hover pattern (referenced below), > sign-in / Ziniao / OTP handling, and the capture rule. This skill documents how to navigate to and export every report type available in Amazon Seller Central and Amazon Advertising, including CSV/PDF structures for building analysis scripts. ## Critical: Hamburger Menu Navigation Many reports are accessed via the **hamburger menu** (top-left corner). This menu uses a **hover-to-reveal** pattern — you must dispatch a `mouseover`, not a `click`, on a category to reveal its submenu items. (See `../amazon-shared/SKILL.md § 4` for the canonical version.) ```bash browser-use <<'PY' # 1. Open the hamburger menu (opens the full sidebar overlay). # The button is a role=button inside the navigation-hamburger-menu # shadow DOM — reach it through its shadow host. js("document.querySelector('navigation-hamburger-menu').shadowRoot.querySelector('[role=button]').click()") wait_for_load() # 2. Reveal the submenu by dispatching mouseover on the "Reports" # category (aria-expanded flips false -> true; flyout appears). js(""" var cat = [...document.querySelectorAll('[aria-expanded=false]')] .find(e => e.textContent.trim() === 'Reports'); cat.dispatchEvent(new MouseEvent('mouseover', {bubbles: true})); """) print(page_info()) # 3. Click the submenu item once it renders (e.g. "Tax Document Library"). js(""" [...document.querySelectorAll('a, [role=button]')] .find(e => e.textContent.trim() === 'Tax Document Library').click(); """) PY ``` **Do NOT click the category name** — clicking navigates away instead of revealing the submenu. Always dispatch `mouseover` first, then `print(page_info())` to see the submenu items, then click the target. If a stable selector isn't obvious, fall back to `capture_screenshot()` then `click_at_xy(x, y)`. ## General Rule: Download Existing Reports First **Before generating any report, always check if a matching report already exists.** All report pages maintain a download history table showing previously generated reports with their date ranges and Download buttons. This applies to ALL report types: - **Fulfillment reports** (`/reportcentral/`): Click the report in the left sidebar → "Download" tab → history table with columns: Report Type | Date Range Covered | Date Requested | File Format | Report Status (Download button). If a row matches the requested date range, click Download directly. - **Advertising reports** (Unified Reporting, `advertising.amazon.{tld}/reporting`): the report list shows saved/generated reports with a **报告状态** column; click into a **已完成** (Completed) row for the Download link. If a completed run matches the date range, download it. (The old `/reports` console is retiring 2026-12-31 — see §6.) - **Payments reports** (`/payments/reports-repository`): Check the report list for existing reports covering the target period. Only request/generate a new report if no existing one covers the needed date range. ## An empty export is a SUCCESS; "N/A" must be proven on the page Two rules that together stop the biggest false-failure pattern (a store was marked FAILED for reports it "doesn't have" — decided from metadata, never checked on the page): **1. Store metadata does NOT tell you which reports apply.** The store's `platforms` / `countries` (e.g. `{"amazon": ["SA"]}`) only say which marketplaces it sells on. They encode **nothing** about FBA enrollment or whether an Advertising account exists. **Never** conclude "no FBA → skip storage/returns" or "no Ads → skip the ad report" from metadata. You must open the actual page and let *it* tell you. **2. A report that exports with zero data rows is DOWNLOADED, not missing.** Request each report on its page: - **Ads report:** warm the ad console first (via Campaign Manager in the Seller Central menu, **or** the `choose-account?destination=/reporting` flow in §6.1) — a **cold** direct `advertising.amazon.{tld}` URL gives a "Sign in / Register" marketing page. Once warm, build the report in Unified Reporting (§6) — Amazon **generates it even with zero campaigns** (headers, 0 rows) → download that empty file, it's a completed deliverable. The ad report is genuinely N/A **only** if, *after* warming up, the store shows an advertiser **onboarding / registration** flow (no advertiser account). A marketing landing reached by direct URL proves nothing — it just means you weren't SSO'd; it is NOT evidence of "no Ads". - **FBA storage / returns:** open the report page and request the month. An empty result / "No Data Available" for a *valid* request still means you asked correctly — download whatever file is produced. Only if the page **explicitly says the store is not enrolled in FBA** is it N/A. **When to use each task outcome:** - **downloaded** (incl. empty 0-row exports) → deliverable met. - **N/A** — only when the *page* proved the capability is absent (advertiser-registration landing; explicit not-enrolled-in-FBA). Record in `vibe_seller_set_task_result`; do **NOT** `vibe_seller_set_task_error`. - **pending-Amazon-latency** (e.g. Monthly Storage Fees not yet published, see §2) → `vibe_seller_set_task_result`, not `vibe_seller_set_task_error`. - **failed** → `vibe_seller_set_task_error` **only** for a report the page shows you *should* be able to get but couldn't (dead button, 0-byte download, error page). If the only gaps are proven-N/A or latency-pending, the task **COMPLETES**. State per report which of {downloaded, N/A-proven-on-page, pending-latency, failed} it is, so the outcome is unambiguous — and never downgrade "I didn't check" into "N/A". ## Clicking a Download button (Amazon `kat-*` shadow DOM) Report tables wrap the Download control as `kat-table-row → kat-table-cell → kat-button`, and the real clickable `<button>` lives **inside `kat-button.shadowRoot`**. A plain `document.querySelector('kat-table-cell button')` (or any `[data-testid=...]` / `.download-btn` guess) returns `null` — CSS selectors do **not** cross shadow boundaries, and `[...document.querySelectorAll('button')]` never sees a button that lives inside a shadow root. So those selectors silently no-op and you waste turns. Reach the inner button through the shadow host and `.click()` it. (This `.click()` works for table Download buttons; the left-sidebar `kat-button`s are the exception — those need a coordinate click.) **Use this one snippet on every report page.** Match the target row by a substring of its date range, then click its Download control: ```bash browser-use <<'PY' print(js(r""" var rowMatch = '01/06/26'; // substring of the TARGET row's date range var rows = document.querySelectorAll('kat-table-row, tr'); for (var r of rows) { if (!(r.textContent || '').includes(rowMatch)) continue; for (var h of r.querySelectorAll('kat-button, kat-link, a, button')) { var real = h.shadowRoot ? h.shadowRoot.querySelector('button, a') : h; var label = (h.textContent||'') + ' ' + ((h.getAttribute && h.getAttribute('label')) || ''); if (real && (h.tagName === 'KAT-BUTTON' || /download|\.csv/i.test(label))) { real.click(); return 'clicked download for row ~ ' + rowMatch; } } } return 'NO download control for ~' + rowMatch + ' (check the date substring / row exists)'; """)) import time; time.sleep(3) # let the download start PY ``` On "NO download control", fall back to `print(page_info())` (it often lists a plain `Download` link, clickable by index) or `capture_screenshot()` + coordinate click — but try the snippet first; it one-shots the common `kat-button` shadow case. The same host-then-inner-button walk applies to any `kat-button` (e.g. "Request Report", "Download CSV") — match on its `label`/text instead of the date substring. ## Setting a custom date range (works across every Seller Central variant) Date controls differ **per marketplace and per report page** — and Amazon changes them over time. You will meet native `<select>` presets, `kat-dropdown` presets, plain `<input>` date fields, `kat-date-picker` / `kat-date-range-picker` shadow widgets, and month/year dropdowns — the same report can render differently on `.sa` vs `.ae` vs `.com`. **Do not assume a widget.** Follow the same three-step loop everywhere: **observe → interact the human way → verify the outcome.** The outcome check is DOM-independent and is what makes this robust. **Step 1 — Observe.** `capture_screenshot()` and glance at the DOM (`document.querySelector('kat-date-range-picker')`? a native `<select>`? plain `input[placeholder]`?). Identify the preset control and, once a custom range is chosen, the two date fields. **Step 2 — Interact the way a human would for THAT widget.** Prefer the interaction that fires the component's real handlers: - **Preset → "Exact dates":** a **native `<select>`** takes a value-set (`el.value='…'` + `change`); a **`kat-dropdown`** does **not** — `click_at_xy` to expand, then `click_at_xy` the "Exact dates" row. - **The two date fields:** the reliable path on **every** variant is the **calendar popup with real clicks** — click the field's calendar icon, `click_at_xy` the **‹ / ›** month arrows to the target month, then `click_at_xy` the day cell. (Locate cells from the screenshot — they aren't reliable via `page_info()`/JS rects.) Plain `<input>` fields on some marketplaces also accept `fill_input(selector, "<date>")` — try it if they truly are light-DOM inputs, but **only trust it after Step 3**. > ⚠️ **On `kat-*` date widgets, programmatic value-setting is > display-only and silently ignored on submit** — live-verified on AE FBA > Customer Returns (2026-07-07): `setAttribute('start-value')`, the > `startValue`/`endValue` property, the nested shadow `<input>.value` + > `input`/`change` events, and CDP `Input.insertText` all updated the > visible field (and even `rp.startValue`) yet the report generated for > **today**. `dropdown.selectOption('-1')` likewise sets `.value` without > emitting the reveal event. The component's submit reads an internal > model only real user input updates — so calendar clicks, not scripts. **Step 3 — Verify the outcome (the universal acceptance test).** This is the check that survives every DOM difference: 1. A quick sanity read after a calendar click — `js("var rp=document.querySelector('kat-date-range-picker'); return rp?rp.startValue+' -> '+rp.endValue:'n/a'")` — is fine as a *first* look, but it is **not authoritative**: a programmatic set can leave `startValue`/`endValue` showing your target without the value actually committing (see the warning above), so a match here does **not** guarantee the report will use it. 2. The authoritative check: request the report, then **CONFIRM the new history row's "Date Range Covered" is your target month, not today.** A today-dated (or wrong) row means the date never committed — go back to Step 2 and use real clicks; do not download the wrong-range file. Because the calendar fills the field itself, **date-format variance (`DD/MM/YYYY` / `MM/DD/YYYY` / `YYYY/M/D`) is irrelevant** — never hand- type the format. Month/year dropdowns (Payments Reports Repository, Monthly Storage Fees) are `kat-dropdown`s → select by real click, never `selectOption()`; month index has been seen **0-indexed** (Jan=0) on some pages — confirm against the visible label, don't hardcode it. **Report-status polling — keep each sleep short.** After requesting a report, poll for the Download button; do **not** `time.sleep(120)` in one call — a single long sleep exceeds the browser-use tool timeout and the turn is killed mid-wait. Loop with short sleeps and re-check instead: ```bash browser-use <<'PY' import time for _ in range(6): # ~6 × 30s ≈ 3 min, each well under the tool timeout time.sleep(30) info = page_info() if 'Download' in info or 'Ready' in info: break print(info) PY ``` ## Critical: One Account, Two Marketplaces — Never Reuse a Download A seller account can span several marketplaces (a MENA account serves both SA and AE). Seller Central then **ignores the URL subdomain and serves the session's last active marketplace**, and the reports come down under names that carry no marketplace at all: 2026JulMonthlyTransaction.csv <- same name for SA and for AE storage.csv <- same name for SA and for AE Both land in the one store downloads dir, so the second marketplace's download **silently overwrites the first**. And if that second download then fails, is slow, or is never actually triggered, `ls -lt` still returns a file under the expected name — the *first* marketplace's — and the agent copies one marketplace's money into both marketplaces' folders. This is not hypothetical. It reached production: a month's report set had one marketplace carrying a second copy of its sibling's revenue, because the same CSV was copied into both target directories. ### Rule 1 — rename before switching marketplace Download → **immediately** move the file to its target directory under its final name → only then switch marketplace and download the next. Never download both marketplaces and sort it out afterwards. ```bash DL=~/.vibe-seller/downloads/<slug> # marketplace 1: download, then move it out at once mv "$DL/2026JulMonthlyTransaction.csv" reports_07_<cc1>_<slug>/2026JulMonthlyTransaction.csv # only now switch the marketplace picker and download the second mv "$DL/2026JulMonthlyTransaction.csv" reports_07_<cc2>_<slug>/2026JulMonthlyTransaction.csv ``` `mv`, not `cp`: it leaves nothing behind in the downloads dir for the next step to pick up by mistake. ### Rules 2 and 3 — one check, run it on every file Both remaining rules read the same two things off a file, so one command covers them. It takes the paths as arguments, finds the header row by shape (the first row with more than five fields — these exports carry preamble lines), then reads the marketplace column **by name**, and streams both the hash and the rows so a large export costs no memory: ```bash python3 - reports_07_<cc1>_<slug>/2026JulMonthlyTransaction.csv \ reports_07_<cc2>_<slug>/2026JulMonthlyTransaction.csv <<'PY' import csv, hashlib, sys for path in sys.argv[1:]: digest = hashlib.md5() with open(path, 'rb') as fh: for chunk in iter(lambda: fh.read(1 << 20), b''): digest.update(chunk) with open(path, newline='', encoding='utf-8-sig') as fh: rows = csv.reader(fh) header = next(r for r in rows if len(r) > 5) cols = [c.strip().lower() for c in header] name = 'marketplace' if 'marketplace' in cols else 'country_code' i = cols.index(name) seen = {r[i].strip().lower() for r in rows if len(r) > i and r[i].strip()}