Analytics

Overview

The Analytics API gives you a unified view of your business performance. Query sales trends, traffic sources, conversion funnels, customer lifetime value, product rankings, and employee metrics — all through a single, consistent interface.

Every endpoint accepts a period parameter (e.g., 7d, 30d, 90d, 1y) and returns comparison data against the previous period so you can spot trends at a glance.

Sales Analytics

Get aggregate sales metrics for any time period. Returns total revenue, order count, average order value, and comparison percentages against the prior equivalent period.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Get sales metrics for the last 30 days
const sales = await whale.analytics.sales({ period: '30d' })

// Response
{
  "period": "30d",
  "revenue": 124850.00,
  "orders": 847,
  "aov": 147.40,
  "comparison": {
    "revenue_change": 12.3,      // +12.3% vs prior 30 days
    "orders_change": 8.1,
    "aov_change": 3.9
  },
  "currency": "USD"
}

Daily & Weekly Breakdown

Break down sales into daily or weekly buckets for charting and trend analysis. Each entry includes revenue, order count, and average order value for that interval.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Daily sales for the last 14 days
const daily = await whale.analytics.dailySales({ period: '14d' })

// Response
{
  "period": "14d",
  "data": [
    { "date": "2026-02-25", "revenue": 4120.00, "orders": 28, "aov": 147.14 },
    { "date": "2026-02-26", "revenue": 5340.00, "orders": 35, "aov": 152.57 },
    { "date": "2026-02-27", "revenue": 3890.00, "orders": 24, "aov": 162.08 },
    // ...
  ]
}

// Weekly sales for the last 12 weeks
const weekly = await whale.analytics.weeklySales({ period: '12w' })

// Response
{
  "period": "12w",
  "data": [
    { "week": "2025-W50", "start": "2025-12-09", "revenue": 31200.00, "orders": 198, "aov": 157.58 },
    { "week": "2025-W51", "start": "2025-12-16", "revenue": 28900.00, "orders": 182, "aov": 158.79 },
    // ...
  ]
}

Traffic & Funnel

Understand where your visitors come from and how they move through the purchase flow. Traffic data includes visit counts, referral sources, and bounce rate. Funnel data shows drop-off at each stage from landing to purchase.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Traffic overview
const traffic = await whale.analytics.traffic({ period: '30d' })

// Response
{
  "period": "30d",
  "total_visits": 42380,
  "unique_visitors": 28910,
  "bounce_rate": 0.34,
  "avg_session_duration_s": 187,
  "sources": [
    { "source": "organic", "visits": 18200, "pct": 0.429 },
    { "source": "direct", "visits": 11400, "pct": 0.269 },
    { "source": "social", "visits": 7100, "pct": 0.168 },
    { "source": "paid", "visits": 3800, "pct": 0.090 },
    { "source": "referral", "visits": 1880, "pct": 0.044 }
  ]
}

// Conversion funnel
const funnel = await whale.analytics.funnel({ period: '30d' })

// Response
{
  "period": "30d",
  "stages": [
    { "stage": "landing", "visitors": 42380, "drop_off": 0.00 },
    { "stage": "product_view", "visitors": 24100, "drop_off": 0.431 },
    { "stage": "add_to_cart", "visitors": 8200, "drop_off": 0.660 },
    { "stage": "checkout_start", "visitors": 3400, "drop_off": 0.585 },
    { "stage": "purchase", "visitors": 2100, "drop_off": 0.382 }
  ],
  "overall_conversion": 0.0495
}

Attribution

Track which marketing channels and campaigns drive revenue. Attribution data breaks down by UTM source, campaign name, and channel, showing visits, conversions, and attributed revenue for each.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Channel attribution for the last 30 days
const attribution = await whale.analytics.attribution({ period: '30d' })

// Response
{
  "period": "30d",
  "channels": [
    {
      "channel": "paid_social",
      "source": "facebook",
      "visits": 3200,
      "conversions": 142,
      "revenue": 18940.00,
      "roas": 4.2,
      "campaigns": [
        { "name": "spring_collection_2026", "visits": 1800, "conversions": 89, "revenue": 11200.00 },
        { "name": "clearance_march", "visits": 1400, "conversions": 53, "revenue": 7740.00 }
      ]
    },
    {
      "channel": "paid_search",
      "source": "google",
      "visits": 2100,
      "conversions": 98,
      "revenue": 14300.00,
      "roas": 3.8,
      "campaigns": [
        { "name": "brand_terms", "visits": 1200, "conversions": 62, "revenue": 8900.00 },
        { "name": "product_keywords", "visits": 900, "conversions": 36, "revenue": 5400.00 }
      ]
    }
  ]
}

Product Analytics

Identify your top-performing products by revenue, units sold, page views, and conversion rate. Use this data to optimize merchandising, pricing, and inventory allocation.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Top products for the last 30 days
const products = await whale.analytics.products({ period: '30d', limit: 5 })

// Response
{
  "period": "30d",
  "products": [
    {
      "product_id": "prod_abc123",
      "name": "Classic Leather Tote",
      "revenue": 12400.00,
      "units_sold": 62,
      "views": 3200,
      "conversion_rate": 0.019,
      "avg_rating": 4.8
    },
    {
      "product_id": "prod_def456",
      "name": "Merino Wool Scarf",
      "revenue": 8900.00,
      "units_sold": 178,
      "views": 5100,
      "conversion_rate": 0.035,
      "avg_rating": 4.6
    },
    // ...
  ]
}

Customer Analytics

Understand your customer base with new vs returning breakdowns, lifetime value cohorts, and retention metrics. Cohorts are grouped by the month a customer first purchased.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Customer analytics for the last 30 days
const customers = await whale.analytics.customers({ period: '30d' })

// Response
{
  "period": "30d",
  "new_customers": 312,
  "returning_customers": 535,
  "returning_rate": 0.632,
  "avg_ltv": 284.50,
  "cohorts": [
    {
      "cohort": "2026-01",
      "customers": 280,
      "total_revenue": 42100.00,
      "avg_orders": 2.1,
      "avg_ltv": 150.36,
      "retention_30d": 0.68,
      "retention_60d": 0.52,
      "retention_90d": 0.41
    },
    {
      "cohort": "2025-12",
      "customers": 310,
      "total_revenue": 68200.00,
      "avg_orders": 3.4,
      "avg_ltv": 220.00,
      "retention_30d": 0.72,
      "retention_60d": 0.58,
      "retention_90d": 0.45
    }
  ]
}

Employee Analytics

Track employee performance across orders processed, revenue generated, and hours worked. Useful for commission calculations, shift optimization, and performance reviews.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Employee performance for the last 30 days
const employees = await whale.analytics.employees({ period: '30d' })

// Response
{
  "period": "30d",
  "employees": [
    {
      "employee_id": "emp_001",
      "name": "Alex Rivera",
      "orders_processed": 142,
      "revenue": 21300.00,
      "avg_order_value": 150.00,
      "hours_logged": 168,
      "revenue_per_hour": 126.79
    },
    {
      "employee_id": "emp_002",
      "name": "Jordan Chen",
      "orders_processed": 118,
      "revenue": 19400.00,
      "avg_order_value": 164.41,
      "hours_logged": 160,
      "revenue_per_hour": 121.25
    }
  ]
}

Projections

Access pre-computed projections and forecasts. Projection types include customer-ltv, revenue-forecast, churn-risk, and inventory-demand. Projections are recalculated nightly using historical data.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Customer LTV projections
const ltv = await whale.analytics.projections('customer-ltv')

// Response
{
  "type": "customer-ltv",
  "computed_at": "2026-03-10T04:00:00Z",
  "model": "probabilistic_cohort_v2",
  "projections": [
    {
      "segment": "high_value",
      "customer_count": 420,
      "projected_12m_ltv": 890.00,
      "confidence": 0.87
    },
    {
      "segment": "mid_value",
      "customer_count": 1840,
      "projected_12m_ltv": 340.00,
      "confidence": 0.82
    },
    {
      "segment": "at_risk",
      "customer_count": 310,
      "projected_12m_ltv": 45.00,
      "confidence": 0.74,
      "recommended_action": "win_back_campaign"
    }
  ]
}

// Revenue forecast
const forecast = await whale.analytics.projections('revenue-forecast')

// Response
{
  "type": "revenue-forecast",
  "computed_at": "2026-03-10T04:00:00Z",
  "forecast": [
    { "month": "2026-04", "projected_revenue": 138000, "low": 121000, "high": 155000 },
    { "month": "2026-05", "projected_revenue": 145000, "low": 124000, "high": 166000 },
    { "month": "2026-06", "projected_revenue": 152000, "low": 128000, "high": 176000 }
  ]
}

API Reference

All analytics endpoints require a valid API key with the analytics scope. Pass the period as a query parameter (e.g., ?period=30d).