Data Kiosk Sales & Traffic Queries: When to Use What

[hakanensari]

Data Kiosk Sales & Traffic Queries: When to Use What

Written by Claude after analyzing production SP-API data and Amazon's documentation.

Amazon's Data Kiosk API offers three ways to query sales and traffic data in the analytics_salesAndTraffic_2024_04_24 schema. Amazon's official documentation explains what each query returns, but doesn't really explain when to use which one. This guide fills that gap based on testing with real seller data.

The Three Query Types

1. salesAndTrafficByDate

What it does: Aggregates sales and traffic across your entire catalog by time period.

Returns: Weekly, daily, or monthly totals for all your products combined.

No limits: Returns data for your entire account.

Example response:

{
  "marketplaceId": "ATVPDKIKX0DER",
  "startDate": "2025-01-05",
  "endDate": "2025-01-11",
  "sales": {
    "orderedProductSales": { "amount": 7557.58, "currencyCode": "USD" },
    "totalOrderItems": 182,
    "unitsOrdered": 182,
    "averageSellingPrice": { "amount": 41.53, "currencyCode": "USD" }
  },
  "traffic": {
    "pageViews": 108355,
    "sessions": 79614,
    "buyBoxPercentage": 13.92,
    "unitSessionPercentage": 0.23
  }
}

2. salesAndTrafficByAsin

What it does: Breaks down sales and traffic by individual ASIN (parent, child, or SKU level).

Returns: Performance data for every ASIN that had activity in your date range.

No limits: Returns all ASINs with sales/traffic data.

Use case: Find your best and worst performers, identify products losing Buy Box, discover unexpected winners.

3. salesAndTrafficTrends

What it does: Tracks specific ASINs over time with your chosen date granularity.

Returns: Time-series data for ASINs you explicitly specify.

Hard limit: Maximum 30 ASINs per marketplace per query.

Use case: Monitor weekly performance of your top products, track new launches, measure the impact of listing changes.

Query Comparison

Feature	byDate	byAsin	trends
Scope	Account-wide totals	All products individually	Specific products only
ASIN limit	N/A (aggregated)	None (returns all)	30 per marketplace
Time series	Yes	One time period	Yes, with date granularity
Best for	Business health KPIs	Product rankings	Tracking key products
Data volume	Small (one row per time period)	Large (row per ASIN)	Medium (30 ASINs × periods)

When to Use What: Catalog Type Matters

The 30-ASIN limit in salesAndTrafficTrends seems arbitrary until you consider what you're actually trying to accomplish. The right query depends heavily on your catalog structure.

Long-Tail Catalog

Profile:

• 1,000+ total ASINs
• Sales distributed across many products
• Most products sell infrequently

Real example from production testing:

• 2,800 average parent items in catalog
• 130 order items per week
• Average: ~0.05 orders per ASIN per week

Recommended approach:

• ✅ salesAndTrafficByDate - Track overall business trends weekly
• ✅ salesAndTrafficByAsin - Monthly deep dive to find patterns
• ❌ salesAndTrafficTrends - Not practical

Why trends don't work here:

The math is straightforward. With 130 orders spread across 2,800 products, tracking 30 specific ASINs means:

• You're monitoring 1% of your catalog
• Most tracked ASINs will show 0-1 sales per week
• Signal-to-noise ratio is too low for meaningful insights

If you wanted to cover even 20% of your weekly sales volume, you'd need to run dozens of separate queries. At that point, salesAndTrafficByAsin is more efficient.

Focused Catalog

Profile:

• 50-500 total ASINs
• Top products drive most revenue
• High velocity on key items

Hypothetical example:

• 200 total ASINs
• Top 30 ASINs = 80% of revenue
• Top performers: 50-200 orders per week each

Recommended approach:

• ✅ salesAndTrafficTrends - Track your top 30 weekly
• ✅ salesAndTrafficByDate - Confirm overall trends
• ⚠️ salesAndTrafficByAsin - Quarterly deep dive for the full catalog

Why trends excel here:

With concentrated sales, tracking 30 ASINs gives you:

• 80%+ visibility into revenue
• Statistically significant weekly data per product
• Early detection of problems (week 1, not month 1)
• Ability to measure listing optimization impact quickly

Hybrid Approach

Profile:

• Large catalog (1,000+ ASINs)
• Clear "star products" (20-30 ASINs drive 60-70% revenue)
• Long tail fills remaining revenue

Recommended approach:

# Weekly: Monitor your stars
top_performers = ["B08N5WRWNW", "B09C3JWXQZ", ...] # Your top 30
trends = query_sales_and_traffic_trends(
  asins: top_performers,
  date_aggregation: :week
)

# Monthly: Overall business health
monthly_kpis = query_sales_and_traffic_by_date(
  aggregation: :month
)

# Quarterly: Find emerging stars
all_products = query_sales_and_traffic_by_asin(
  start_date: three_months_ago
)
rising_stars = all_products.select { |p| p.growth_rate > 0.5 }

This approach gives you:

• Real-time visibility on products that matter most
• Discovery mechanism for long-tail winners
• Complete business metrics

Real Production Data: Long-Tail Example

Here's actual data from a production seller account tested with Peddler (6 months, weekly aggregation):

Account characteristics:

• Marketplace: US (ATVPDKIKX0DER)
• ~2,800 parent items in catalog
• ~$143K total revenue over 6 months

Weekly metrics (sample week: Jan 5-11, 2025):

{
  ordered_product_sales: "$7,557.58",
  shipped_product_sales: "$8,674.19",
  total_order_items: 182,
  units_ordered: 182,
  average_selling_price: "$41.53",
  page_views: 108_355,
  sessions: 79_614,
  buy_box_percentage: 13.92,
  unit_session_percentage: 0.23
}

Key observations:

• Conversion rate: 0.23% (182 units ÷ 79,614 sessions)
• High traffic volume but distributed across ~2,800 products
• Average ~4 page views per product per day
• Individual ASINs: 0-2 sales per week for most products

Why trends would be problematic:

If this seller used salesAndTrafficTrends on 30 random ASINs:

• Expected sales per tracked ASIN per week: 182 ÷ 2,800 × 30 = ~2 units
• Most weeks: Many ASINs would show zero sales
• Meaningful trend analysis requires consistent volume

For this seller, salesAndTrafficByDate provides exactly what they need: overall business health, conversion trends, and Buy Box performance across the entire catalog.

The 30-ASIN Limitation Explained

Why does this limit exist? Probably a combination of API performance, result size management, and encouraging focused queries.

What 30 ASINs means for different catalogs:

Catalog Size	Coverage	Practical Use
50 ASINs	60%	Track majority of catalog
200 ASINs	15%	Track top performers
1,000 ASINs	3%	Track only your stars
5,000 ASINs	0.6%	Barely useful

This isn't a bug—it's a feature design decision. salesAndTrafficTrends is purpose-built for focused product tracking, not comprehensive catalog analysis.

Practical Examples

Example 1: New Product Launch

query {
  analytics_salesAndTraffic_2024_04_24 {
    salesAndTrafficTrends(
      startDate: "2025-01-01"
      endDate: "2025-03-31"
      asinAggregation: CHILD
      dateAggregation: WEEK
      filters: [{
        marketplaceId: "ATVPDKIKX0DER"
        asins: ["B0NEWPRODUCT1"]
      }]
    ) {
      childAsin
      startDate
      endDate
      sales { unitsOrdered }
      traffic { sessions, unitSessionPercentage }
    }
  }
}

Track your new product's first 90 days week-by-week. See if it's gaining traction or needs intervention.

Example 2: Overall Business Health

query {
  analytics_salesAndTraffic_2024_04_24 {
    salesAndTrafficByDate(
      startDate: "2025-01-01"
      endDate: "2025-12-31"
      marketplaceIds: ["ATVPDKIKX0DER"]
      aggregateBy: MONTH
    ) {
      startDate
      endDate
      sales {
        orderedProductSales { amount, currencyCode }
        totalOrderItems
      }
      traffic {
        sessions
        buyBoxPercentage
        unitSessionPercentage
      }
    }
  }
}

Get monthly business KPIs: revenue, orders, traffic, conversion, Buy Box performance.

Example 3: Product Performance Audit

query {
  analytics_salesAndTraffic_2024_04_24 {
    salesAndTrafficByAsin(
      startDate: "2025-01-01"
      endDate: "2025-01-31"
      marketplaceIds: ["ATVPDKIKX0DER"]
      aggregateBy: PARENT
    ) {
      parentAsin
      sales { orderedProductSales { amount } }
      traffic { sessions, unitSessionPercentage }
    }
  }
}

Get every product's January performance. Sort by revenue, find high-traffic-low-conversion products, identify Buy Box problems.

Key Takeaways

1. Most sellers should start with salesAndTrafficByDate for overall business metrics and trends.

2. Use salesAndTrafficByAsin for deep dives when you need to understand product-level performance across your full catalog.

3. Reserve salesAndTrafficTrends for focused tracking of your most important products (new launches, top performers, products under optimization).

4. The 30-ASIN limit is significant - do the math for your catalog before building around trends.

5. Amazon's docs don't explain this - they tell you what each query does, not when to use it.

Testing in Peddler

You can see working examples in Peddler's test suite:

• SalesAndTraffic20231115Test - Shows the query workflow
• Production VCR cassettes show real response structures

The 2024-04-24 schema has identical field structures to 2023-11-15, so all parsing code remains the same. The main changes:

• Query field name updated
• marketplaceIds parameter now required (was optional)
• New salesAndTrafficTrends query added

Amazon's Documentation

Amazon's official documentation is surprisingly minimal on strategic guidance:

• Changelog: Analytics Sales and Traffic update
• API Reference: Data Kiosk API
• GraphQL Schema: analytics_salesAndTraffic_2024_04_24.graphql

The GraphQL schema file has the most detailed field-level documentation, but doesn't address catalog-type considerations or use case guidance.