Analytics

Three layers, from cheapest to richest: store dashboard counters (short-lived caches), lite orders reports (lor) — compact 8-day rollups built for sparklines — and timeline analytics for charts and the confirmation desk. Everything requires a Bearer token.

Store dashboard counters

summary and chart are cached server-side for 60 seconds per store and range (with singleflight, so concurrent dashboards share one query). Both require the orders.read permission on the store.

curl -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/stores/{id}/summary?from=2026-08-01T00:00:00Z&to=2026-08-13T00:00:00Z"

Lite orders reports (LOR)

A lite orders report is a compact, cache-friendly rollup for one scope — a store, a product, or a product landing page:

{
  "lor": {
    "lastSync": "2026-08-13T20:12:01.000Z",
    "lastItemDate": "2026-08-13",
    "totalOrders": 1284,
    "data": [[12, 3, 5], [9, 1, 7], [0, 0, 0], [14, 2, 6], [11, 0, 4], [8, 2, 3], [10, 1, 9], [4, 0, 2]]
  }
}

• data always has 8 rows — one per UTC calendar day, oldest first, ending today. Each row is [completed, cancelled, rest] order counts for that day (rest = every other status).
• totalOrders is the all-time order count for the scope (soft-deleted excluded).
• Reports are cached for ~6 hours with per-scope jitter (±30 min) so scopes don't all expire together. A stale report is refreshed incrementally: the 8-day window slides and only missing days are recomputed; if older orders changed since lastSync, the window is fully rebuilt.
• The batch endpoints read from day-level rollup tables, so the query count stays flat no matter how many stores or products you request.

LOR endpoints require the store's analytics permission. Batch responses return { "lor": { "id": { … } }, "skipped": [ … ] } — ids the caller may not view (or that don't exist) land in skipped instead of failing the whole request.

curl -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/stores/{storeId}/analytics/lor"

curl -X POST "https://api.feeef.org/v1/stores/analytics/lor/batch" \
  -H "Authorization: Bearer $FEEEF_TOKEN" -H "Content-Type: application/json" \
  -d '{"storeIds": ["STORE_A", "STORE_B"]}'

Timelines & breakdowns

RPC-style POST endpoints under /v1/actions/analytics. All take storeId plus optional shared filters: productId, status, tags, confirmerId. Time-series endpoints take ISO from / to and a step in seconds (3600 to 2592000, default 86400 = daily buckets keyed dd-MM-yyyy).

Semantics worth knowing:

• Financial timeline — revenue is subtotal + shipping_price, cancelled orders are excluded, and cost comes from each item's product cost × quantity. Returns revenues, costs, profits, orders maps plus totals.
• Count by field — returns a counts map, the unfiltered total, and truncated: true when more distinct values exist than limit (1–100, default 20).
• Confirmation insights — scoped to orders assigned to a confirmer. topProducts splits assigned orders into success / failed / delivered; hourly is a dense 24-slot histogram in the caller's local time (pass tzOffsetMinutes, e.g. 60 for UTC+1); confirmerTopProducts (top 3 per confirmer) is included only in the team view (no confirmerId).

Results are cached server-side: 30 minutes for both timelines, 1 hour for count-by-field, and 2 minutes for confirmation insights (it powers a live operations dashboard). None of these four are wrapped by the SDKs yet.

curl -X POST "https://api.feeef.org/v1/actions/analytics/getFinancialTimeline" \
  -H "Authorization: Bearer $FEEEF_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "storeId": "STORE_ID",
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-08-13T23:59:59.999Z",
    "step": 86400
  }'