amazon-sp-sales-traffic-analyzer v0.4.0A

Immutable. This exact content never changes and is served at /api/v1/blob/7047fc7da042a686.

---
name: amazon-sp-sales-traffic-analyzer
description: Use when analyzing Amazon Seller Central Sales & Traffic Business Reports or GET_SALES_AND_TRAFFIC_REPORT data for traffic, conversion, ordered sales, ASIN performance, daily trends, or optional Amazon Business B2B segmentation.
license: PolyForm-Shield-1.0.0 (see LICENSE.txt)
compatibility: Requires Python 3.10+ and a writable filesystem to run the bundled analyzer and create report artifacts.
metadata:
  version: "0.4.0"
---

# Sales & traffic analyzer (Amazon Business Reports)

## Overview

Primary lens: **traffic and sales health** from the **Sales & Traffic** export (ASIN or parent-product grain depending on file). **B2B vs non-B2B** is an optional assessment layer: include it only when B2B fields are present and comparable; otherwise state **B2B N/A** and complete the rest of the analysis.

## When to Use

- Portfolio or ASIN-level **sessions**, **page views**, **buy box %**, **unit session %** (conversion), **units ordered**, **orders**, **sales**
- Identifying high-traffic / low-conversion ASINs and the inverse
- **B2B revenue share**, top B2B ASINs, B2B-heavy SKUs, "grow B2B" candidates — **only when fields exist**
- Narratives for Amazon Business pricing, quantity discounts — grounded in observed B2B metrics, not assumed
- **Daily trends** — DoD, moving average, DOW patterns, WoW, spike/drop flags when a date column exists and the user wants time-series insight (or when the file is daily grain)

## Agent workflow (required)

1. **Confirm scope** — Marketplace, currency, date range, ASIN grain, source format, and date granularity. Run daily trend calculations only for daily-grain data.
2. **Acquire and route data** — Upload, API, or warehouse. Use the bundled analyzer only for `GET_SALES_AND_TRAFFIC_REPORT` JSON. Seller Central CSV/XLSX exports require column introspection and a bounded local analyzer. Data Kiosk JSONL/GraphQL results have a different schema and require separate normalization. Never feed either format directly to `scripts/compute_metrics.py`.
3. **Introspect** — Columns, dtypes, row counts, sample rows. Map Amazon's verbose headers to semantic roles.
4. **Build `COLUMN_MAP`** — At minimum: ASIN (or SKU/parent key), **sessions** (and/or page views), **ordered product sales** (amount), **units ordered**; optional **orders**, **buy box %**, **unit session %**, **page views**; optional **B2B** sales/units/orders columns. See `references/column-mapping-hints.md`.
5. **Validate definitions** — Confirm one marketplace and one currency per analysis. If total and B2B sales exist, verify matching attribution and `0 ≤ B2B ≤ total`. Label `total − B2B` as **non-B2B residual**, not consumer-attributed revenue. If validation fails, report B2B and total separately.
6. **Compute metrics deterministically** — For known Reports API JSON, run `scripts/compute_metrics.py` and use its compact metrics JSON as the source of truth. Do not ask the LLM to recreate those calculations.
7. **Generate the report from metrics** — the LLM writes `sales_traffic_analysis.md` using `references/report-template.md`, the compact metrics JSON, and the user's objective. Charts (trend lines, DOW bars, B2B share) are **optional** if the user's environment supports visualization; default deliverable is **markdown tables**. Do not create a separate QA markdown deliverable; perform checks internally and reflect data-quality notes inside `sales_traffic_analysis.md`.

## Required deliverables

When data is available, produce these filesystem artifacts before final response:

| File | Required contents |
|------|-------------------|
| `sales_traffic_metrics.json` | Compact deterministic metrics from `scripts/compute_metrics.py`; this is the only data artifact the LLM should reason over. |
| `sales_traffic_analysis.md` | LLM-generated business report using `references/report-template.md`, populated from `sales_traffic_metrics.json`. |

Do not deliver only a process note, checklist, prerequisites document, or plan when the report data is present. The final response should point to the generated report and summarize the top findings.

## SP-API JSON input shape

For `GET_SALES_AND_TRAFFIC_REPORT` API downloads, expect nested JSON instead of flat export columns:

- `reportSpecification`: report type, marketplaces, data start/end time, and options such as `dateGranularity` and `asinGranularity`
- `salesAndTrafficByDate[]`: each row usually contains `date`, `salesByDate`, and `trafficByDate`
- `salesAndTrafficByAsin[]`: each row usually contains `parentAsin`, `childAsin`, `salesByAsin`, and `trafficByAsin`

Validate `reportType`, array shapes, and the single marketplace before computing. `dateGranularity` can be `DAY`, `WEEK`, or `MONTH`; DoD, MA7, weekday/weekend, and seven-day WoW apply only to `DAY`. Validate every observed `currencyCode`; never infer USD or aggregate mixed currencies.

Normalize valid Reports API JSON into date and ASIN tables. Preserve whether optional B2B fields are absent instead of converting absence into a reported zero.

## Metrics script contract

Use `scripts/compute_metrics.py` for known Amazon SP-API Sales & Traffic report JSON. It computes metrics only and emits compact JSON; it does **not** write final prose.

Example:

```bash
python scripts/compute_metrics.py \
  --input /data/sales_and_traffic_report.json \
  --metrics-out /workspace/sales_traffic_metrics.json \
  --top-n 10 \
  --anomaly-threshold-pct 20 \
  --low-conversion-min-sessions 100 \
  --low-conversion-max-pct 10 \
  --b2b-heavy-min-share-pct 50 \
  --pretty
```

The output JSON includes `source`, `row_counts`, `portfolio`, `daily_trends`, `asin_rankings`, `b2b`, and `validation`. `source.analysis_parameters` records every configurable threshold. `daily_trends.available` states whether daily calculations were valid. Use the compact JSON plus `references/report-template.md` for narrative and recommendations.

## Context-bloat boundary

Large source files must stay outside the model context. Do not use generic file-reading tools to load a full JSON/CSV/XLSX report into the conversation. Use a bounded local analyzer/tool/script that reads the raw file locally and returns only compact artifacts: schema/key summary, row counts, date range, aggregate metrics, validation failures, and capped top-N tables.

The agent may reason over the compact metrics payload and write the final report from that payload. If more information is needed, request another bounded aggregate or capped top-N result; do not ask for raw rows or the full file content.

## Code execution rule

For known Amazon SP-API Sales & Traffic JSON, run `scripts/compute_metrics.py` instead of authoring new metric code. For unknown or materially different exports, write/run a bounded local analysis script instead of reading the full file into model context. The local script must return compact metrics, validation errors, and capped top-N tables only.

Default to Python standard-library code for portable sandbox execution. Do not import pandas, numpy, polars, matplotlib, or other third-party packages unless you have already verified they are installed. If execution fails because a package is unavailable, rewrite the script with the standard library and rerun it; do not stop with an installation/prerequisite report when the input data is present.

## Acceptance checks

Before final response, verify `sales_traffic_analysis.md` includes:

- Date range, marketplace/source, grain, and row counts
- Total ordered product sales
- Total sessions
- Total units ordered
- B2B revenue and share, or `B2B N/A` with a reason
- Non-B2B residual only when `validation.b2b_subset_valid` is true
- Daily trend table only for validated daily-grain data
- Top ASINs by revenue
- Top ASINs by sessions or page views
- Recommendations tied to computed metrics from this run

## What not to do

- Do not exit the entire analysis because B2B columns are missing — **still report traffic and sales**.
- Do not assume `reports[0]['report_data']` or fixed column substring lists without printing headers first.
- Do not label `total − B2B` as consumer-attributed revenue. Report it as a non-B2B residual only after subset validation.
- Do not recommend Business pricing changes without tying to B2B share or opportunity metrics from **this** file.

## Core metrics (semantic)

| Area | Typical metrics | Notes |
|------|-----------------|--------|
| Traffic | Sessions, page views | May be one or both |
| Conversion | Unit session %, orders / sessions | Use file column if present; else derive with care |
| Sales | Ordered product sales, units, orders | Match currency |
| Buy Box | Buy Box % | Weight portfolio values by page views and state the method |
| B2B (if present) | B2B sales, B2B units, B2B share of revenue | Optional section |
| Trends (daily) | DoD %, MA7, deviation vs MA, WoW, DOW averages | Optional §2 in template |

## Resources

| Path | Contents |
|------|----------|
| `references/report-template.md` | Full report sections (optional daily trends + traffic + sales + optional B2B) |
| `references/time-series-trends.md` | Daily aggregation, MA, anomalies, WoW, and DOW methodology |
| `references/b2b-segments.md` | B2B-heavy, opportunities, thresholds (tunable) |
| `references/column-mapping-hints.md` | Header hints for Sales & Traffic + B2B + date |
| `references/agent-codegen-patterns.md` | Source routing, aggregation, non-B2B residuals, and group-by-date trends |
| `scripts/compute_metrics.py` | Deterministic Sales & Traffic metrics JSON generator |

## Quality bar

- Lead with **traffic and sales** findings; place optional **B2B and non-B2B** context after baseline metrics (or mark the B2B block N/A).
- Every percentage shows **numerator/denominator** or column name source.
- Call out **data quality** (null sessions, mixed parent/child rows) before strong conclusions.