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 `hover`, not `click`, on a category to reveal its submenu items. ```bash # 1. Open the hamburger menu browser-use state # find the menu button (role=button inside navigation-hamburger-menu shadow DOM) browser-use click <menu-btn> # opens the full sidebar overlay # 2. Reveal submenu by hovering browser-use state # find "Reports" (aria-expanded=false) browser-use hover <reports-idx> # changes aria-expanded to true, reveals flyout # 3. Click the submenu item browser-use state # find target item (e.g. "Tax Document Library") browser-use click <item-idx> # navigates to the page ``` **Do NOT click the category name** — clicking navigates away instead of revealing the submenu. Always `hover` first, then `state` to see submenu items, then `click` the target. ## 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** (`advertising.amazon.{tld}/reports`): The list page shows existing reports with date ranges in the right scroll panel. Click the report name to reach the detail page → history table with Download link. If a completed run matches the date range, download it. - **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. ## Report Types Overview ### A. Seller Central Reports (via hamburger menu → Reports) | # | Report | Direct URL Path | Export Type | Wait Time | |---|--------|----------------|-------------|-----------| | 1 | Business Reports | `/business-reports` | CSV download | Instant | | 2 | Custom Analytics | (new feature) | Varies | Varies | | 3 | Fulfillment | `/reportcentral/WelcomePage` | Request → Download | 1-5 min | | 4 | Advertising Reports | Redirects to Ad console | CSV download | Hours/Days | | 5 | Return Reports | `/reportcentral/WelcomePage` | Request → Download | 1-5 min | | 6 | Custom Reports | `/listing/reports` | Request → Download | 1-5 min | | 7 | Inventory Reports | `/inventory-reports` | Request → Download | 1-5 min | | 8 | Tax Document Library | `/tax/seller-fee-invoices` | View (PDF) | Instant | | 9 | Manage Taxes | `/tax/tax-settings` | Settings page | N/A | | 10 | Selling Economics & Fees | `/selling-economics-and-fees` | Dashboard | Varies | ### B. Payments Reports | Report | Direct URL Path | Export Type | Wait Time | |--------|----------------|-------------|-----------| | Reports Repository | `/payments/reports-repository` | Request → CSV | 1-3 min | ### C. Advertising Reports (separate console) | Report | URL Pattern | Export Type | Wait Time | |--------|-------------|-------------|-----------| | Sponsored Ads Reports | `advertising.amazon.{tld}/reports` | CSV download | 5 min – 24 hours | --- ## 1. Business Reports **Navigation**: hamburger menu → hover Reports → Business Reports **Direct URL**: `https://sellercentral.amazon.{tld}/business-reports` **Lands on**: `#/dashboard` (Sales Dashboard) ### Sub-sections (left sidebar) - **Dashboards** → Sales Dashboard - **By Date** → Sales and Traffic, Detail Page Sales and Traffic, Seller Performance - **By ASIN** → Detail Page Sales and Traffic, By Parent Item, By Child Item ### Export Flow ```bash browser-use open "https://sellercentral.amazon.{tld}/business-reports" browser-use state # find "Download" button (inside shadow DOM kat-table-cell) browser-use click <download-btn> # triggers CSV download — immediate ``` ### Wait Time **Instant** — page data is pre-loaded, Download button exports current view. --- ## 2. Fulfillment Reports **Navigation**: hamburger menu → hover Reports → Fulfillment **Direct URL**: `https://sellercentral.amazon.{tld}/reportcentral/WelcomePage` ### Sub-reports (left sidebar, elements have `id=report-nav-link-url`) | Category | Reports | |----------|---------| | Inventory | Inventory ledger report, Stranded Inventory, Reserved Inventory, Amazon Fulfilled Inventory, Manage FBA Inventory | | Shipping | Inbound Performance, Outlet Deals | | Orders | Amazon Fulfilled Shipments, Amazon Fulfilled Shipments – Tax Invoicing, All Orders | | Fees | Fee Preview, Monthly Storage Fees, Aged Inventory Surcharge report | | Returns | Reimbursements, FBA customer returns, Replacements, Removal Order Detail, Removal Shipment Detail | | Other | EPR Category Reports | ### Export Flow ```bash browser-use open "https://sellercentral.amazon.{tld}/reportcentral/WelcomePage" browser-use state # find report link in sidebar (id=report-nav-link-url) browser-use click <report-link> # opens specific report browser-use state # find "Request Report" / date range / "Generate Report" browser-use click <request-btn> # Wait 1-5 minutes. Refresh page to check status. browser-use open "https://sellercentral.amazon.{tld}/reportcentral/WelcomePage" browser-use state # find "Download" button when status shows ready browser-use click <download-btn> ``` ### Wait Time **1-5 minutes** for most reports. Refresh the page to check status. ### Monthly Storage Fees — publication latency **Observed behavior:** requesting Monthly Storage Fees for the previous month early in the new month returns `No Data Available` on the detail page even though the request itself is accepted. The same month's range re-requested about a week later returns a Download button within ~30s. Older months (M-2, M-3) request successfully right away. So Storage Fees for month M is **not** available on day 7 of M+1 but **is** available by day 13-14 of M+1. The exact day Amazon publishes is not documented on the page; the page header for this report says only "Report data 24 hours old" (about freshness of already-published values, not about when they appear). **How to handle a `No Data Available` Storage Fees response when the requested month is the previous calendar month:** 1. Don't keep retrying within the same task — Amazon won't surface the data sooner because of repeat requests. 2. Produce every other expected file (Transaction CSV, FBA Customer Returns CSV, Sponsored Products advertised-product XLSX) — those publish on a different cadence and ARE available today. 3. A scheduled re-run after roughly day 13-14 of the following month will capture the storage CSV. **Task-status decision for this scenario — MANDATORY exception to the system-prompt's "MUST call vibe_seller_set_task_error when primary objective could not be fully completed" rule:** If the ONLY missing deliverable is `storage.csv` (any country) and the cause is this Amazon publication-latency window (today is in month M+1, Amazon's detail page says `No Data Available`), then: - Call `vibe_seller_set_task_result(<full report including a "Storage CSV pending Amazon publication" note>)` with the partial summary. - **DO NOT call `vibe_seller_set_task_error`.** The task lands COMPLETED — the next scheduled run picks up storage when Amazon publishes it. Calling `set_task_error` here causes the task to land FAILED for what is a known, expected, upstream-paced data state, and that triggers false "task failed" alerts downstream. This is a NARROW exception. It applies only when: (a) every other deliverable for the task ran successfully, AND (b) the only gap is `storage.csv`, AND (c) the agent saw `No Data Available` on the report-history detail page for that exact month. If ANY other deliverable also failed, fall back to the normal "call BOTH set_task_result and set_task_error" pattern from the system prompt — the storage-latency exception does not absorb unrelated failures. If `No Data Available` shows for an **older** month (≥ ~30 days old), that's unexpected — investigate normally; do not wave away, and do call `set_task_error`. ### FBA Customer Returns — Exact dates flow (MANDATORY for month ranges) **Direct URL**: `https://sellercentral.amazon.{tld}/reportcentral/CUSTOMER_RETURNS/1` The date control is NOT a From/To pair like other reports. It is a **preset dropdown** (initial title `last day (yesterday)`) whose options are last 1/3/7/14/30/90/180 days — **plus an `Exact dates` option (`kat-option value=-1`)** at the bottom. Presets are anchored to *today*, so "last 30 days" does NOT equal a calendar month: on June 3 it covers May 4 → June 3, silently dropping May 1–3 and mixing in June rows. **Never use a preset when the task asks for a calendar month.** Correct flow: ```bash browser-use open "https://sellercentral.amazon.{tld}/reportcentral/CUSTOMER_RETURNS/1" browser-use state # find preset dropdown (title="last day (yesterday)") browser-use click <preset-dropdown> browser-use state # options list; "Exact dates" is value=-1 browser-use click <exact-dates-option> browser-use state # TWO plain inputs appear: # aria-label="Start date", aria-label="End date" # placeholder DD/MM/YYYY browser-use input <start-idx> "01/01/2026" browser-use input <end-idx> "31/01/2026" browser-use click <request-csv-btn> # "Request .csv Download" # ~30s; first row of the history table shows the range + Download browser-use state browser-use click <download-btn> ``` **Anti-pattern — do NOT do this:** after clicking `Exact dates`, do not try to set the `kat-date-picker` values via `browser-use eval` / shadow-DOM JS. Setting `.value` on kat-date-picker silently fails (one observed run burned ~100 steps this way and fell back to a wrong preset). After clicking the option, just re-run `browser-use state` — the Start/End fields surface as ordinary indexed `<input>` elements and `browser-use input <idx> <text>` works directly. (Note the CLI verb is `input`, not `type` — `type` does not take an element index.) **UTC edge rows are normal:** the date filter is marketplace-local, but the CSV's `return-date` column is UTC. A row dated the last day of the *previous* month at ~21:00–23:59 UTC is the 1st of the requested month in local time — keep it, don't re-request. The download lands as a numeric report id (e.g. `51901234567.csv`) in the store downloads dir; rename to `return.csv` when the task asks for that exact name. --- ## 3. Tax Document Library **Navigation**: hamburger menu → hover Reports → Tax Document Library **Direct URL**: `https://sellercentral.amazon.{tld}/tax/seller-fee-invoices` ### Page Structure - **Tab**: Seller Fee Invoices (default and only tab) - Displays most recent 1,000 invoices. Click "Load More" at bottom for older. - **Invoices grouped by month** (newest first) ### Table Columns ``` Invoice Type | Invoice File Type | Invoice Number | Payer Name | Payer Registration | Supplier Name | Supplier Registration | Marketplace | Start Date | End Date | Action ``` ### Invoice Types | Invoice Type | Description | |-------------|-------------| | Fulfillment by Amazon Tax Invoice | FBA service fees invoice | | Merchant VAT Credit Note | VAT credit adjustment | | Merchant VAT Invoice | VAT invoice for seller fees | | Product Ads VAT Invoice | Advertising VAT invoice | ### Invoice Number Format `{CC}-{ENTITY}-INV-{YEAR}-{SEQ}` (invoices) or `{CC}-{ENTITY}-CN-{YEAR}-{SEQ}` (credit notes) Where `{CC}` = country code (e.g. `US`), `{ENTITY}` = Amazon entity code, `{SEQ}` = sequence number. ### Export Flow ```bash browser-use open "https://sellercentral.amazon.{tld}/tax/seller-fee-invoices" browser-use state # find View buttons (id=view_invoice_button-announce) # Each "View" button has a value=urn:alx:ver:{UUID} attribute # Clicking triggers a form POST that downloads a PDF browser-use click <view-btn-idx> # For a specific month, search state output for date strings: # e.g. "Mar 01" or "Mar 31" for March invoices # For older invoices beyond most recent 1,000: browser-use scroll down # to bottom browser-use state # find "Load More" browser-use click <load-more-btn> ``` ### Wait Time **Instant** — invoices are already generated, View triggers immediate PDF download. ### PDF Content (for analysis) Each PDF is a formal tax invoice containing: invoice number, dates, seller and supplier VAT details, line items with amounts, VAT calculations, totals. These are individual documents — not bulk-exportable as CSV. --- ## 4. Custom Reports (Listing Reports) **Navigation**: hamburger menu → hover Reports → Custom Reports **Direct URL**: `https://sellercentral.amazon.{tld}/listing/reports` ### Report Types (dropdown values) - Active Listings Report - All Listings Report ### Table Columns ``` Report Type | Batch ID (timestamp) | Report Status | Action (Download) ``` ### Export Flow ```bash browser-use open "https://sellercentral.amazon.{tld}/listing/reports" browser-use state # find "Select Report Type" dropdown and "Request Report" # Select type browser-use click <dropdown> browser-use state # find options browser-use click <report-type-option> # Request browser-use click <request-btn> # Wait 1-5 minutes, then check for Download browser-use state # table shows new row with status browser-use click <download-btn> ``` ### Wait Time **1-5 minutes**. Refresh page to check if Report Status = ready. --- ## 5. Payments Reports Repository **Navigation**: hamburger menu → hover Payments → Payments, then tab "Reports Repository".