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.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `period` | `"today" \| "7d" \| "30d" \| "90d" \| "12m"` | `30d` | Preset window. Ignored when `from`/`to` are supplied. |
| `from` | `string` | – | ISO 8601 start. Overrides `period`; requires `to`. |
| `to` | `string` | – | ISO 8601 end. Overrides `period`; requires `from`. |

`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).

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

### Response

```json
{
  "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).

```bash
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

```json
{
  "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 }
  ]
}
```