Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway.

Analytics API

Access business analytics, reporting, and data insights across all operations.

Overview

Attribute	Value
Base Path	`/api/v1/analytics`
Authentication	Bearer Token
Required Roles	`analytics_admin`, `data_analyst`, `restaurant_manager`, `platform_admin`, `system_admin`, `super_admin`, `pos_staff`, `server`, `restaurant_staff`, `manager`, `tenant_admin`
Data Freshness	Near real-time (< 5 min)

Dashboard Metrics

Get Dashboard Summary

Retrieve key metrics for dashboard.

GET /api/v1/analytics/dashboard

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location (or `all`)
`date`	date	Specific date (default: today)
`compare_to`	string	`previous_day`, `previous_week`, `previous_year`

Response

{
  "date": "2026-01-24",
  "location_id": "loc_123",
  "sales": {
    "total": 12450.00,
    "orders": 285,
    "avg_ticket": 43.68,
    "comparison": {
      "period": "previous_day",
      "total": 11200.00,
      "change_percent": 11.2
    }
  },
  "labor": {
    "total_hours": 125.5,
    "labor_cost": 2137.50,
    "labor_percent": 17.2,
    "employees_on_clock": 12
  },
  "guests": {
    "total": 342,
    "avg_party_size": 2.4,
    "avg_check_per_guest": 36.40
  },
  "order_channels": {
    "dine_in": {"orders": 145, "revenue": 7250.00},
    "takeout": {"orders": 85, "revenue": 3400.00},
    "delivery": {"orders": 55, "revenue": 1800.00}
  },
  "top_items": [
    {"name": "Ribeye Steak", "quantity": 45, "revenue": 1575.00},
    {"name": "Burger Combo", "quantity": 68, "revenue": 884.00}
  ]
}

Sales Analytics

Get Sales Report

Detailed sales analytics.

GET /api/v1/analytics/sales

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`start_date`	date	Report start
`end_date`	date	Report end
`granularity`	string	`hour`, `day`, `week`, `month`
`group_by`	string	`category`, `channel`, `server`, `daypart`

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "summary": {
    "gross_sales": 298500.00,
    "discounts": 12450.00,
    "net_sales": 286050.00,
    "tax": 25744.50,
    "tips": 42907.50,
    "total_collected": 354702.00,
    "orders": 6850,
    "avg_ticket": 41.76,
    "guests": 8562
  },
  "by_day": [
    {
      "date": "2026-01-24",
      "gross_sales": 12450.00,
      "orders": 285,
      "avg_ticket": 43.68
    }
  ],
  "by_category": [
    {"category": "Food", "sales": 215000.00, "percent": 75.2},
    {"category": "Beverage", "sales": 55500.00, "percent": 19.4},
    {"category": "Alcohol", "sales": 15550.00, "percent": 5.4}
  ],
  "by_channel": [
    {"channel": "Dine-In", "sales": 185000.00, "orders": 4250},
    {"channel": "Takeout", "sales": 68500.00, "orders": 1850},
    {"channel": "Delivery", "sales": 32550.00, "orders": 750}
  ],
  "by_daypart": [
    {"daypart": "Breakfast", "sales": 35000.00, "percent": 12.2},
    {"daypart": "Lunch", "sales": 95000.00, "percent": 33.2},
    {"daypart": "Dinner", "sales": 156050.00, "percent": 54.6}
  ]
}

Get Hourly Sales

Sales broken down by hour.

GET /api/v1/analytics/sales/hourly

Response

{
  "date": "2026-01-24",
  "hours": [
    {"hour": 11, "sales": 1250.00, "orders": 28},
    {"hour": 12, "sales": 2850.00, "orders": 65},
    {"hour": 13, "sales": 1950.00, "orders": 44},
    {"hour": 18, "sales": 2150.00, "orders": 48},
    {"hour": 19, "sales": 2650.00, "orders": 58}
  ],
  "peak_hour": 12,
  "peak_sales": 2850.00
}

Labor Analytics

Get Labor Report

GET /api/v1/analytics/labor

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`start_date`	date	Report start
`end_date`	date	Report end
`group_by`	string	`role`, `employee`, `department`

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "summary": {
    "total_hours": 3250.5,
    "regular_hours": 3050.0,
    "overtime_hours": 200.5,
    "total_labor_cost": 55258.50,
    "labor_percent_of_sales": 19.3,
    "avg_hourly_rate": 17.00,
    "employees_worked": 45
  },
  "by_role": [
    {
      "role": "Server",
      "hours": 1250.0,
      "cost": 18750.00,
      "employees": 15
    },
    {
      "role": "Cook",
      "hours": 850.0,
      "cost": 15300.00,
      "employees": 10
    }
  ],
  "by_day": [
    {
      "date": "2026-01-24",
      "hours": 145.5,
      "cost": 2473.50,
      "labor_percent": 19.9
    }
  ],
  "overtime_detail": [
    {
      "employee_id": "emp_001",
      "name": "John Smith",
      "regular_hours": 40,
      "overtime_hours": 8.5,
      "overtime_cost": 255.00
    }
  ]
}

Get Labor vs Sales

GET /api/v1/analytics/labor/vs-sales

Response

{
  "date": "2026-01-24",
  "hourly": [
    {
      "hour": 11,
      "sales": 1250.00,
      "labor_cost": 180.00,
      "labor_percent": 14.4,
      "employees": 8
    },
    {
      "hour": 12,
      "sales": 2850.00,
      "labor_cost": 240.00,
      "labor_percent": 8.4,
      "employees": 12
    }
  ],
  "optimal_staffing_suggestions": [
    {
      "hour": 14,
      "current_employees": 10,
      "recommended": 8,
      "potential_savings": 36.00
    }
  ]
}

Product Analytics

Get Product Mix

GET /api/v1/analytics/products

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`start_date`	date	Report start
`end_date`	date	Report end
`category`	string	Filter by category
`sort_by`	string	`revenue`, `quantity`, `profit`

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "items": [
    {
      "item_id": "item_001",
      "name": "Ribeye Steak",
      "category": "Entrees",
      "quantity_sold": 850,
      "gross_revenue": 29750.00,
      "cost": 12750.00,
      "profit": 17000.00,
      "margin_percent": 57.1,
      "avg_order_freq": 12.4
    }
  ],
  "categories": [
    {
      "category": "Entrees",
      "items_sold": 4500,
      "revenue": 125000.00,
      "profit": 68750.00
    }
  ],
  "trends": {
    "trending_up": [
      {"name": "Truffle Fries", "change_percent": 25.5}
    ],
    "trending_down": [
      {"name": "Garden Salad", "change_percent": -12.3}
    ]
  }
}

Get Modifier Analysis

GET /api/v1/analytics/products/modifiers

Response

{
  "data": [
    {
      "modifier_name": "Add Bacon",
      "times_selected": 1250,
      "revenue_generated": 3750.00,
      "selection_rate": 15.2
    },
    {
      "modifier_name": "Substitute Fries",
      "times_selected": 850,
      "revenue_generated": 1700.00,
      "selection_rate": 10.3
    }
  ]
}

Customer Analytics

Get Customer Insights

GET /api/v1/analytics/customers

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "summary": {
    "total_customers": 2850,
    "new_customers": 450,
    "returning_customers": 2400,
    "avg_visits_per_customer": 2.4,
    "avg_lifetime_value": 185.00
  },
  "retention": {
    "30_day_retention": 65.5,
    "60_day_retention": 48.2,
    "90_day_retention": 35.8
  },
  "segments": [
    {
      "segment": "VIP",
      "count": 125,
      "revenue": 45000.00,
      "avg_ticket": 72.00
    },
    {
      "segment": "Regular",
      "count": 850,
      "revenue": 85000.00,
      "avg_ticket": 45.00
    }
  ],
  "acquisition": {
    "walk_in": 1850,
    "online": 650,
    "referral": 200,
    "marketing": 150
  }
}

Operational Analytics

Get Service Times

GET /api/v1/analytics/operations/service-times

Response

{
  "date": "2026-01-24",
  "summary": {
    "avg_ticket_time_minutes": 18.5,
    "avg_table_turn_minutes": 52.3,
    "avg_kitchen_time_minutes": 12.8,
    "avg_delivery_time_minutes": 35.2
  },
  "by_order_type": [
    {
      "type": "dine_in",
      "avg_time_minutes": 48.5,
      "orders": 145
    },
    {
      "type": "takeout",
      "avg_time_minutes": 15.2,
      "orders": 85
    }
  ],
  "by_hour": [
    {"hour": 12, "avg_time_minutes": 22.5, "orders": 65},
    {"hour": 18, "avg_time_minutes": 16.8, "orders": 48}
  ],
  "bottlenecks": [
    {
      "station": "Grill",
      "avg_wait_minutes": 8.5,
      "peak_wait_minutes": 15.2
    }
  ]
}

Trend Analysis

Get Trends

GET /api/v1/analytics/trends

Query Parameters

Parameter	Type	Description
`metric`	string	`sales`, `orders`, `customers`, `labor`
`period`	string	`7d`, `30d`, `90d`, `1y`
`granularity`	string	`day`, `week`, `month`

Response

{
  "metric": "sales",
  "period": "30d",
  "data": [
    {"date": "2025-12-25", "value": 8500.00},
    {"date": "2025-12-26", "value": 9200.00},
    {"date": "2026-01-24", "value": 12450.00}
  ],
  "statistics": {
    "min": 7850.00,
    "max": 15200.00,
    "avg": 10850.00,
    "median": 10500.00,
    "std_dev": 1850.00
  },
  "trend": {
    "direction": "up",
    "change_percent": 8.5,
    "forecast_next_period": 13200.00
  }
}

Comparisons

Compare Locations

GET /api/v1/analytics/compare/locations

Query Parameters

Parameter	Type	Description
`location_ids`	string[]	Locations to compare
`metrics`	string[]	Metrics to compare
`start_date`	date	Period start
`end_date`	date	Period end

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "locations": [
    {
      "location_id": "loc_123",
      "name": "Downtown",
      "metrics": {
        "sales": 186500.00,
        "orders": 4250,
        "avg_ticket": 43.88,
        "labor_percent": 18.5
      }
    },
    {
      "location_id": "loc_456",
      "name": "Uptown",
      "metrics": {
        "sales": 98500.00,
        "orders": 2600,
        "avg_ticket": 37.88,
        "labor_percent": 21.2
      }
    }
  ],
  "rankings": {
    "sales": ["loc_123", "loc_456"],
    "efficiency": ["loc_123", "loc_456"]
  }
}

Export Reports

Generate Report

Request a report export.

POST /api/v1/analytics/reports

Request Body

{
  "report_type": "sales_summary",
  "format": "xlsx",
  "parameters": {
    "start_date": "2026-01-01",
    "end_date": "2026-01-24",
    "location_id": "loc_123"
  },
  "delivery": {
    "method": "email",
    "email": "manager@example.com"
  }
}

Response

{
  "report_id": "rpt_abc123",
  "status": "generating",
  "estimated_completion": "2026-01-24T19:05:00Z"
}

Get Report Status

GET /api/v1/analytics/reports/{report_id}

Response

{
  "report_id": "rpt_abc123",
  "status": "completed",
  "download_url": "https://...",
  "expires_at": "2026-01-25T19:00:00Z"
}

Webhooks

Event	Description
`analytics.report_ready`	Scheduled report generated
`analytics.alert_triggered`	Metric threshold exceeded

Error Responses

Status	Code	Description
400	`invalid_date_range`	Date range exceeds limit
400	`invalid_granularity`	Granularity not supported
403	`location_access_denied`	No access to location
429	`rate_limited`	Too many requests

Reports API - Standard reports
Dashboard API - Dashboard builder
AI Insights - AI-powered insights

Overview​

Dashboard Metrics​

Get Dashboard Summary​

Sales Analytics​

Get Sales Report​

Get Hourly Sales​

Labor Analytics​

Get Labor Report​

Get Labor vs Sales​

Product Analytics​

Get Product Mix​

Get Modifier Analysis​

Customer Analytics​

Get Customer Insights​

Operational Analytics​

Get Service Times​

Trend Analysis​

Get Trends​

Comparisons​

Compare Locations​

Export Reports​

Generate Report​

Get Report Status​

Webhooks​

Error Responses​

Related Documentation​

Overview

Dashboard Metrics

Get Dashboard Summary

Sales Analytics

Get Sales Report

Get Hourly Sales

Labor Analytics

Get Labor Report

Get Labor vs Sales

Product Analytics

Get Product Mix

Get Modifier Analysis

Customer Analytics

Get Customer Insights

Operational Analytics

Get Service Times

Trend Analysis

Get Trends

Comparisons

Compare Locations

Export Reports

Generate Report

Get Report Status

Webhooks

Error Responses

Related Documentation