Analytics API

REST API endpoints for store performance metrics and sales over time.

Read store performance metrics. Both endpoints share the same range selector – a preset period (default last 30 days) or an explicit from/to window – and compare figures against the preceding equal-length period to compute growth percentages.

All monetary values (revenue, average order value) are returned in minor units (e.g. cents for USD, pence for GBP). Divide by 100 (or the appropriate factor for the currency) to get the display amount.

Range Parameters

These query parameters apply to every analytics endpoint.

from and to must be provided together, and from must be before to.

Overview

GET /api/v1/analytics/overview

Headline KPIs for the window: revenue, order count, average order value, new/returning customers, the order-status breakdown, and the top 5 products by revenue. Each top product also carries cogs and coveredUnits – the cost of the units sold and how many of them had a known cost, so a partially costed catalogue is visible rather than silently inflating margin. Revenue, orders, and customer figures include growth versus the preceding equal-length period. Money is in minor units (cents).

curl -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/analytics/overview?period=30d"

Response

{
  "range": {
    "startDate": "2024-05-16T10:30:00.000Z",
    "endDate": "2024-06-15T10:30:00.000Z"
  },
  "currency": "USD",
  "revenue": {
    "total": "1245000",
    "orders": 184,
    "averageOrderValue": "6766.304347826087",
    "revenueGrowth": 12.4,
    "ordersGrowth": 8.1
  },
  "customers": {
    "total": 152,
    "new": 47,
    "returning": 105,
    "growth": 5.3
  },
  "ordersByStatus": [
    { "status": "paid", "count": 120, "percentage": 65 },
    { "status": "shipped", "count": 50, "percentage": 27 },
    { "status": "completed", "count": 14, "percentage": 8 }
  ],
  "topProducts": [
    {
      "productId": "0191abc0-0000-7000-8000-000000000100",
      "productName": "Classic Tee",
      "slug": "classic-tee",
      "totalQuantity": 96,
      "totalRevenue": "288000",
      "orderCount": 72,
      "cogs": "121000",
      "coveredUnits": 84
    }
  ]
}

Sales

GET /api/v1/analytics/sales

Total revenue and orders for the window, plus a daily series. Each entry in series is a UTC day bucket with date (YYYY-MM-DD), revenue, gross, and orders. revenue is net of refunds and gross is the same bucket before them. Both are in minor units (cents).

curl -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/analytics/sales?from=2024-06-01T00:00:00.000Z&to=2024-06-15T00:00:00.000Z"

Response

{
  "range": {
    "startDate": "2024-06-01T00:00:00.000Z",
    "endDate": "2024-06-15T00:00:00.000Z"
  },
  "currency": "USD",
  "total": "612000",
  "orders": 90,
  "revenueGrowth": 14.2,
  "series": [
    { "date": "2024-06-01", "revenue": 41000, "gross": 43500, "orders": 6 },
    { "date": "2024-06-02", "revenue": 52500, "gross": 52500, "orders": 8 }
  ]
}