Digital-shelf audit pipeline
A staged pipeline that audits a CPG brand's entire Amazon presence (availability, content health, pricing, seller mix, ratings) and renders a self-contained HTML dashboard an executive can open with no login and no explanation.
- System
- A five-stage batch pipeline (discover → fetch → parse → metrics → render) over the Keepa API, with cost estimation before any spend, resume-safe runs, and a raw JSON cache designed to be queried by Claude afterward.
- Stack
- PythonKeepa APIChart.jsopenpyxlClaude (ad-hoc analysis)
- Validation
- Every scored pillar traces to raw cached fields, so any number on the dashboard can be audited back to the API response that produced it. Scoring logic was reviewed against listings the team already knew were healthy or broken before the first client-facing run.
- Outcome
- A shelf audit that took an analyst days of manual lookup now runs in one command, is reproducible, and leaves behind a queryable dataset instead of a dead PDF.
The loop
human checkpoint
- discover
Find the brand's top products by sales rank, plus tracked competitors, to define the audit universe.
Keepa API
- estimate
Before fetching, the tool prints exactly what the run will cost in API tokens and wall-clock wait, and stops.
why a human here The person running the audit owns the API budget. A printed estimate turns "the script spent $40" into "I approved $40."
- fetch
A token-optimized request recipe pulls each product for ~2 tokens. Raw JSON is cached to disk, so a crashed or interrupted run resumes where it stopped instead of re-spending.
Keepa APIJSON cache
- parse + score
Raw data becomes eight scored pillars (availability, discoverability, demand, content health, seller mix, ratings, pricing, listing structure) with parent/child listing families nested correctly.
Python
- render
A single self-contained HTML file with the scorecard, product drill-downs, competitor comparison, and sales-rank trends, plus an Excel backup for the analysts.
Chart.jsopenpyxl
- interrogate
Claude reads the cached JSON directly, so "which child ASINs lost the buy box last month?" doesn't need a new script.
Claude
The problem
“How healthy is our Amazon presence?” is a simple question that used to take days to answer: dozens of listings, each checked by hand for stock, content, pricing, and who’s winning the buy box. It got answered once a quarter at best, and the answer aged instantly.
Design decisions worth explaining
Cost is surfaced before it’s incurred. The pipeline’s second stage exists only to print a token and time estimate and wait for a yes. Nobody runs a script twice if the first run surprised them with a bill.
Runs are resume-safe. Every fetched product lands in a JSON cache before parsing begins. Network failure at product 180 of 240 means resuming at 181, not re-paying for 180.
The dashboard is a single file. No server, no login, no dependencies. It gets attached to an email and opens in any browser. Distribution friction kills internal tools faster than missing features do.
The cache is the second product. The dashboard covers the standing questions. For everything else, the raw JSON is shaped so Claude can read it, and the follow-ups nobody predicted become a conversation with the data.
Where the human sits, and why
Two checkpoints. The spend approval is about budget ownership. The other is that the dashboard informs a recommendation rather than triggering actions, because shelf strategy is a client-relationship call, not a scoring-rubric call. The middle of the pipeline runs unsupervised since every step’s output is checkable against its input.