The /analytics endpoint provides aggregated performance metrics powered by BigQuery. Use it to build dashboards, reports, and integrations that need summary data rather than raw transaction records.

Endpoint

GET /v2/analytics
Authorization: Bearer <idToken>

All queries require a type parameter and the corresponding scope ID.

Query Types

Employee Analytics

GET /v2/analytics?type=employee&employeeId=emp_xxx&environment=live

{
  "type": "employee",
  "employeeId": "emp_xxx",
  "source": "bigquery",
  "totalTips": 150,
  "totalAmount": 2500.00,
  "avgTipAmount": 16.67,
  "totalRatings": 120,
  "averageRating": 4.6,
  "availableBalance": 250.00,
  "thisWeekTips": 125.00,
  "lastWeekTips": 98.00,
  "thisWeekTipCount": 8,
  "lastWeekTipCount": 6,
  "thisWeekRatings": 7,
  "lastWeekRatings": 5
}

Property Analytics

GET /v2/analytics?type=property&propertyId=prop_xxx&environment=live

Returns the same metrics as employee analytics but aggregated across all employees at the property. Also includes dateRange in the response.

Organization Analytics

GET /v2/analytics?type=organization&organizationId=org_xxx&environment=live

Returns org-wide totals plus per-property breakdown.

Department Analytics

GET /v2/analytics?type=department&departmentId=dept_xxx&environment=live

Outlet Analytics

GET /v2/analytics?type=outlet&outletId=out_xxx&environment=live

Leaderboard

GET /v2/analytics?type=leaderboard&organizationId=org_xxx&limit=10&environment=live

Returns top employees ranked by tip amount or count within the organization:

{
  "type": "leaderboard",
  "leaderboard": [
    { "rank": 1, "employeeId": "emp_aaa", "name": "Maria G.", "totalAmount": 950.00, "tipCount": 42 },
    { "rank": 2, "employeeId": "emp_bbb", "name": "James T.", "totalAmount": 820.00, "tipCount": 38 }
  ]
}

Time Series

GET /v2/analytics?type=timeseries&employeeId=emp_xxx&startDate=2026-01-01&endDate=2026-03-25&environment=live

Returns daily or weekly aggregated data points suitable for charts:

{
  "type": "timeseries",
  "series": [
    { "date": "2026-03-24", "tipCount": 3, "tipAmount": 42.50, "avgRating": 4.7 },
    { "date": "2026-03-25", "tipCount": 5, "tipAmount": 78.00, "avgRating": 5.0 }
  ]
}

Conversion Funnel (Requires Visit Records)

GET /v2/analytics?type=funnel&propertyId=prop_xxx&startDate=2026-03-01&endDate=2026-03-25&environment=live

{
  "type": "funnel",
  "totalVisits": 250,
  "visitsWithRating": 85,
  "visitsWithTip": 62,
  "ratingConversion": 0.34,
  "tipConversion": 0.25
}

Requires visit records to be populated (see Visits API or Room Charge integration).

Date Range Filtering

Add startDate and endDate (ISO8601) to any query type:

?startDate=2026-03-01&endDate=2026-03-31

If omitted, the API defaults to the last 30 days.

Data Source

Responses include a source field indicating whether data came from bigquery or firestore (fallback). BigQuery data may lag real-time by a few minutes; Firestore fallback is fully real-time but may lack some aggregated metrics.

Access Control

  • Employees can query their own analytics (employeeId must match their own record).
  • Managers can query their team (departmentId, outletId).
  • PropertyAdmins can query any scope within their property.
  • OrganizationAdmins can query the full organization.