4 sections, 15 terms. The vocabulary used across every lens: what each metric measures, how the data actually moves through the pipeline, and the architectural decisions baked into v1.
Marketplace mechanics
Marketplace mechanics
The Amazon-specific terms that shape what we measure.
ASIN
Amazon Standard Identification Number. The 10-character ID Amazon assigns to every product. The cross-channel join key in the warehouse; every fact row about an Amazon listing carries an ASIN.
Buy-box
The 'Add to Cart' panel on an Amazon product page. Whichever seller wins the buy-box gets the sale by default. Beats wants to own the buy-box on every owned ASIN; losing it to a third party means we just gave away that sale.
MAP (Minimum Advertised Price)
The lowest price Beats authorizes retailers to advertise. A retailer or third-party seller pricing below MAP is a contractual violation and is often the signal of a diverted-inventory channel.
Third-party seller
Any seller on Amazon that is not Beats or an authorized retailer. Healthy listings have a small set of authorized resellers. A growing 3P count on a single ASIN is a counterfeit / diversion early warning.
BSR (Best Sellers Rank)
Amazon's category-level rank for a product. Lower is better. We surface BSR alongside shelf-search rank because they answer different questions: BSR is 'how many people bought it', shelf rank is 'how visible it was to searchers'.
Metrics & signals
Metrics & signals
How we score what each lens shows.
MAP-violation flag
Set automatically when a channel's listed price falls below the product's MAP for at least one snapshot. Surfaces in red on the price grid; rolled up by count on the seller landscape.
Cross-channel price grid
The matrix on Lens 1. Each Beats SKU as a row, each retailer as a column, current price in each cell. MAP violations highlight red; out-of-stock shows distinctly.
Shelf rank
A product's position in Amazon's organic search results for a given keyword. Like Google SoV (BEA-04 Competitive Observatory) but on Amazon's own surface. Top-3 captures most shopper attention.
Suspect listing (heuristic)
An Amazon listing flagged by simple rules: seller account younger than 90 days, no rating history, or listing price more than 25% below MAP. Not a court-ready signal, useful as a triage queue.
Pipeline
Pipeline
How the data moves through the warehouse.
Merchant API (DataForSEO)
DataForSEO's commerce endpoints. merchant_amazon_asin returns price, buy-box, and rating per ASIN. merchant_amazon_sellers returns the 3P seller list. merchant_google_shopping covers non-Amazon retailers indirectly.
Append-only
Every ingest writes a NEW row with a captured_at timestamp. Lets us reconstruct any historical state (price trends, buy-box flips, seller-count growth) by query rather than by maintaining a separate snapshot system.
Star schema (dim_* / fact_*)
Warehouse pattern. dim_entity, dim_product (ASIN-keyed), dim_channel, dim_keyword, dim_date hold rarely-changing reference data. fact_marketplace_listing, fact_marketplace_sellers, and fact_amazon_rank hold the append-only measurements.
Clearance registry
The data-fabric package tracks every external source with a clearance status (cleared, pending, blocked) and an owner. The Marketplace Observatory calls assertCleared('dataforseo-amazon') before every adapter call. If the source isn't cleared, the call fails fast.
Spend & kill criteria
Spend & kill criteria
Cost governance baked into the dashboard.
Spend cap (MTD chip)
Month-to-date DataForSEO spend, color-coded in the page header. Green under $50, amber from $50 to $100, red at $100. The $100 cap is a hard kill criterion; sweeps halt automatically when crossed.
Hard kill / soft warn
Two thresholds enforced in code. SOFT_WARN at $50 is visual amber only. HARD_KILL at $100 means ingest scripts refuse to fire. Override sunk cost.