Search Documentation

Search for a documentation page...

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.

Range Parameters

These query parameters apply to every analytics endpoint.

ParameterTypeDefaultDescription
period"today" | "7d" | "30d" | "90d" | "12m"30dPreset window. Ignored when from/to are supplied.
fromstring—ISO 8601 start. Overrides period; requires to.
tostring—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. Revenue, orders, and customer figures include growth versus the preceding equal-length period.

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": "12450.00",
    "orders": 184,
    "averageOrderValue": "67.66",
    "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": "2880.00",
      "orderCount": 72
    }
  ]
}

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, and orders.

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": "6120.00",
  "orders": 90,
  "revenueGrowth": 14.2,
  "series": [
    { "date": "2024-06-01", "revenue": 410, "orders": 6 },
    { "date": "2024-06-02", "revenue": 525, "orders": 8 }
  ]
}
PreviousSocialsAPI ReferenceNextSettingsAPI Reference