Analytics API

The Analytics API provides event ingestion, metric queries, and pre-built dashboard endpoints for monitoring commerce performance in real time.

Event Structure

{
  "id": "evt_abc123",
  "event": "order_completed",
  "userId": "user_xyz789",
  "sessionId": "sess_001",
  "timestamp": "2024-01-15T10:35:00Z",
  "properties": {
    "orderId": "order_abc123",
    "total": 6578,
    "currency": "USD",
    "items": 3
  },
  "context": {
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0 ...",
    "page": "/checkout/confirm"
  }
}

Event Tracking

Track Event

POST /analytics/event

curl -X POST https://api.hanzo.ai/analytics/event \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "product_view",
    "userId": "user_xyz789",
    "properties": {
      "productId": "prod_abc123",
      "name": "Premium T-Shirt",
      "price": 2999,
      "currency": "USD"
    }
  }'

Response: 201 Created

{
  "id": "evt_def456",
  "event": "product_view",
  "timestamp": "2024-01-15T10:36:00Z"
}

Track Batch Events

POST /analytics/event/batch

Send multiple events in a single request:

curl -X POST https://api.hanzo.ai/analytics/event/batch \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event": "page_view",
        "userId": "user_xyz789",
        "properties": {"page": "/products/shirts"}
      },
      {
        "event": "product_view",
        "userId": "user_xyz789",
        "properties": {"productId": "prod_abc123"}
      }
    ]
  }'

Standard Events

Event	Properties
`page_view`	`page`, `referrer`
`product_view`	`productId`, `name`, `price`
`add_to_cart`	`productId`, `variantId`, `quantity`
`remove_from_cart`	`productId`, `quantity`
`checkout_started`	`cartId`, `total`, `itemCount`
`order_completed`	`orderId`, `total`, `currency`
`search`	`query`, `resultCount`

Query Endpoints

Sales Overview

GET /analytics/sales

Query Parameters:

Parameter	Type	Description
`period`	string	`7d`, `30d`, `90d`, `12m`
`granularity`	string	`hour`, `day`, `week`, `month`
`currency`	string	Filter by currency

curl "https://api.hanzo.ai/analytics/sales?period=30d&granularity=day" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "period": "30d",
  "revenue": 125000,
  "orders": 450,
  "averageOrderValue": 27778,
  "currency": "USD",
  "growth": {
    "revenue": 12.5,
    "orders": 8.3
  },
  "series": [
    {"date": "2024-01-15", "revenue": 4500, "orders": 16},
    {"date": "2024-01-14", "revenue": 3800, "orders": 14}
  ]
}

Product Performance

GET /analytics/products

curl "https://api.hanzo.ai/analytics/products?period=30d&limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "topSellers": [
    {
      "productId": "prod_abc123",
      "name": "Premium T-Shirt",
      "revenue": 15000,
      "unitsSold": 500,
      "conversionRate": 20.0
    }
  ]
}

Customer Metrics

GET /analytics/customers

curl "https://api.hanzo.ai/analytics/customers?period=30d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Funnel Analysis

GET /analytics/funnel

curl "https://api.hanzo.ai/analytics/funnel?period=7d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "stages": [
    {"name": "Product Views", "count": 10000, "rate": 100},
    {"name": "Add to Cart", "count": 2500, "rate": 25},
    {"name": "Checkout Started", "count": 1200, "rate": 48},
    {"name": "Order Completed", "count": 780, "rate": 65}
  ],
  "conversionRate": 7.8
}

Dashboard Data

Real-Time Stats

GET /analytics/realtime

curl "https://api.hanzo.ai/analytics/realtime" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "activeVisitors": 142,
  "ordersToday": 28,
  "revenueToday": 8450,
  "topPages": [
    {"page": "/products/shirts", "visitors": 34},
    {"page": "/collections/sale", "visitors": 21}
  ]
}

Custom Query

POST /analytics/query

Run custom metric queries:

curl -X POST https://api.hanzo.ai/analytics/query \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["revenue", "orders", "aov"],
    "dimensions": ["product_category", "region"],
    "filters": {
      "period": "30d",
      "currency": "USD"
    },
    "orderBy": "revenue:desc",
    "limit": 20
  }'

Export Data

GET /analytics/export

curl "https://api.hanzo.ai/analytics/export?type=orders&period=30d&format=csv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o orders_report.csv

Export Formats: csv, json, xlsx

Analytics data is processed in near real-time. Event ingestion is acknowledged immediately, and metrics are available for querying within 30 seconds.

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

const commerce = new Commerce({ apiKey: 'your_key' })

// Track event
await commerce.analytics.track('product_view', {
  productId: 'prod_abc123',
  userId: 'user_xyz789'
})

// Get sales overview
const sales = await commerce.analytics.getSales({ period: '30d' })

// Custom query
const report = await commerce.analytics.query({
  metrics: ['revenue', 'orders'],
  dimensions: ['product_category'],
  filters: { period: '7d' }
})

Go

err := client.Analytics.Track(ctx, &sdk.AnalyticsEvent{
    Event:  "product_view",
    UserID: "user_xyz789",
    Properties: map[string]interface{}{
        "productId": "prod_abc123",
    },
})

sales, err := client.Analytics.GetSales(ctx, &sdk.SalesQuery{
    Period: "30d",
})

report, err := client.Analytics.Query(ctx, &sdk.AnalyticsQuery{
    Metrics:    []string{"revenue", "orders"},
    Dimensions: []string{"product_category"},
    Filters:    map[string]string{"period": "7d"},
})

On this page