Hydra is now in beta|Get started free|Follow our journey on X.com

Analytics API
On this page

Analytics

The analytics endpoints provide pre-aggregated KPIs and time-series data for merchant dashboards. Data is computed from daily stats tables (populated by a nightly cron job) with live queries supplementing “today” numbers in real-time.

All monetary values are in cents (e.g. 4999 = $49.99). The currency field in each response indicates the store’s base currency.

Base URL: https://api.hydrajs.dev

Endpoints

Method Path Auth Description
GET /v1/analytics/summary Secret Get analytics summary
GET /v1/analytics/revenue Secret Get revenue time series
GET /v1/analytics/orders Secret Get orders time series
GET /v1/analytics/top-products Secret Get top products
GET /v1/analytics/action-items Secret Get action items

Get analytics summary

GET /v1/analytics/summary

Returns aggregated KPIs for a date range with optional comparison to a previous period. Includes revenue, orders, average order value, items sold, refunds, new customers, and returning customer rate.

Query parameters

Parameter Type Description
from string Start date (YYYY-MM-DD). Defaults to 30 days ago.
to string End date (YYYY-MM-DD). Defaults to today.
compare string Comparison mode: previous_period (default), previous_year, none

Request

curl "https://api.hydrajs.dev/v1/analytics/summary?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "period": { "from": "2026-08-01", "to": "2026-08-31" },
    "comparison_period": { "from": "2026-07-01", "to": "2026-07-31" },
    "metrics": {
      "gross_revenue": { "value": 145000, "previous": 120000, "change": 20.83 },
      "net_revenue": { "value": 140000, "previous": 118000, "change": 18.64 },
      "orders": { "value": 42, "previous": 35, "change": 20 },
      "average_order_value": { "value": 3452, "previous": 3429, "change": 0.67 },
      "items_sold": { "value": 87, "previous": 70, "change": 24.29 },
      "refunds": { "value": 5000, "previous": 2000, "change": 150 },
      "new_customers": { "value": 18, "previous": 15, "change": 20 },
      "returning_customer_rate": { "value": 35.71, "previous": 28.57, "change": 25 }
    },
    "currency": "usd"
  }
}

Each metric includes value (current period), previous (comparison period, null if compare=none), and change (percentage change, null if previous is zero or comparison disabled).

Get revenue time series

GET /v1/analytics/revenue

Returns revenue time-series data at day, week, or month granularity. Days with no orders appear as zeros.

Query parameters

Parameter Type Description
from string Start date (YYYY-MM-DD). Defaults to 30 days ago.
to string End date (YYYY-MM-DD). Defaults to today.
interval string Aggregation interval: day (default), week, month

Request

curl "https://api.hydrajs.dev/v1/analytics/revenue?from=2026-08-25&to=2026-08-31&interval=day" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "interval": "day",
    "series": [
      { "date": "2026-08-25", "gross_revenue": 12500, "net_revenue": 12500, "orders": 3 },
      { "date": "2026-08-26", "gross_revenue": 0, "net_revenue": 0, "orders": 0 },
      { "date": "2026-08-27", "gross_revenue": 8900, "net_revenue": 8900, "orders": 2 }
    ],
    "currency": "usd"
  }
}

Get orders time series

GET /v1/analytics/orders

Returns order count, items sold, and average order value at day, week, or month granularity.

Query parameters

Parameter Type Description
from string Start date (YYYY-MM-DD). Defaults to 30 days ago.
to string End date (YYYY-MM-DD). Defaults to today.
interval string Aggregation interval: day (default), week, month

Request

curl "https://api.hydrajs.dev/v1/analytics/orders?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "interval": "day",
    "series": [
      { "date": "2026-08-01", "orders": 5, "items_sold": 12, "average_order_value": 3200 },
      { "date": "2026-08-02", "orders": 0, "items_sold": 0, "average_order_value": 0 }
    ],
    "currency": "usd"
  }
}

Get top products

GET /v1/analytics/top-products

Returns top products ranked by revenue or quantity sold for a date range.

Query parameters

Parameter Type Description
from string Start date (YYYY-MM-DD). Defaults to 30 days ago.
to string End date (YYYY-MM-DD). Defaults to today.
limit integer Number of products to return (1–20, default 5)
sort_by string Sort by: revenue (default), quantity

Request

curl "https://api.hydrajs.dev/v1/analytics/top-products?limit=3&sort_by=revenue" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": [
    {
      "product_id": "prod_abc123",
      "title": "Premium Cotton T-Shirt",
      "image_src": "https://cdn.hydrajs.dev/store_123/img_456.webp",
      "revenue": 89500,
      "quantity_sold": 25,
      "orders": 20
    },
    {
      "product_id": "prod_def456",
      "title": "Classic Denim Jacket",
      "image_src": null,
      "revenue": 45000,
      "quantity_sold": 10,
      "orders": 9
    }
  ]
}

Get action items

GET /v1/analytics/action-items

Returns live counts of items requiring attention. No query parameters.

Request

curl "https://api.hydrajs.dev/v1/analytics/action-items" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "unfulfilled_orders": 5,
    "low_stock_items": 3,
    "pending_returns": 1
  }
}

Object reference

Metric

Field Type Description
value integer/number Current period value
previous integer/null Previous period value (null if comparison disabled)
change number/null Percentage change (null if previous is 0 or N/A)

Revenue series entry

Field Type Description
date string Date (YYYY-MM-DD)
gross_revenue integer Total revenue in cents
net_revenue integer Revenue minus refunds, cents
orders integer Number of orders

Orders series entry

Field Type Description
date string Date (YYYY-MM-DD)
orders integer Number of orders
items_sold integer Total items sold
average_order_value integer Average order value in cents

Top product

Field Type Description
product_id string Product ID
title string Product title
image_src string/null Primary image URL
revenue integer Total revenue in cents
quantity_sold integer Total quantity sold
orders integer Number of orders

Action items

Field Type Description
unfulfilled_orders integer Paid orders awaiting fulfillment
low_stock_items integer Variants at or below low-stock threshold
pending_returns integer Return requests awaiting approval