# Mobile API: Today's Performance Endpoint

## Overview

The `todayPerformance` endpoint returns detailed KPI (Key Performance Indicator) data for a store's daily performance. This matches the "Today's Performance" expanded view in the web workbook.

## Endpoint

```
POST /api/mobile/todayPerformance/:typeNum
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key (POST body) |
| `typeNum` | string | Yes | Store identifier (URL path, e.g., `pc00`) |
| `store` | string | No | Optional override for typeNum (POST body) |

## Example Request

```bash
curl -X POST https://buyerkiosk.com/api/mobile/todayPerformance/pc00 \
  -d "APIKey=your_api_key_here"
```

## Response

### Success Response (HTTP 200)

```json
{
  "success": true,
  "date": "2025-12-01",
  "storeId": "pc00",

  "sales": {
    "current": 1875.25,
    "formatted": "$1,875.25",
    "goal": 2500.00,
    "goalFormatted": "$2,500.00",
    "variance": -624.75,
    "varianceFormatted": "-$624.75",
    "comp": 0,
    "compFormatted": "$0.00",
    "status": "danger"
  },

  "avgTrans": {
    "current": 45.50,
    "formatted": "$45.50",
    "goal": 0,
    "goalFormatted": "--",
    "comp": 42.00,
    "compFormatted": "$42.00",
    "status": "neutral"
  },

  "tradePercent": {
    "current": 22.69,
    "formatted": "22.69%",
    "goal": 15,
    "goalFormatted": "15.00%",
    "comp": 18.50,
    "compFormatted": "18.50%",
    "status": "danger"
  },

  "salesLabor": {
    "transactions": 41,
    "laborHours": 5.58,
    "laborHoursFormatted": "5.6",
    "salesPerLaborHour": 336.02,
    "salesPerLaborHourFormatted": "$336.02",
    "totalWages": 105.74,
    "totalWagesFormatted": "$105.74"
  },

  "backstock": {
    "pulled": 12,
    "added": 5,
    "recentActivity": [
      {
        "time": "14:30",
        "bin": "A1",
        "action": "Pulled",
        "category": "Tops"
      },
      {
        "time": "13:45",
        "bin": "B3",
        "action": "New Product",
        "category": "Dresses"
      }
    ]
  },

  "buys": {
    "count": 8,
    "countFormatted": "8",
    "compBuys": 425.00,
    "compBuysFormatted": "$425.00",
    "tradeTotal": 150.00,
    "tradeTotalFormatted": "$150.00",
    "percentTraded": 35.29,
    "percentTradedFormatted": "35.29%",
    "compTradePercent": 28.50,
    "compTradePercentFormatted": "28.50%"
  }
}
```

### Error Responses

**Store Not Found (HTTP 404)**
```json
{
  "error": "Store not found"
}
```

**Missing API Key (HTTP 400)**
```json
{
  "error": "Missing APIKey parameter"
}
```

**Server Error (HTTP 500)**
```json
{
  "success": false,
  "error": "Failed to fetch KPI data",
  "message": "Error details..."
}
```

## Response Fields

### Top Level

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Whether the request succeeded |
| `date` | string | Date of the KPI data (YYYY-MM-DD) |
| `storeId` | string | Store identifier |

### Sales Object

| Field | Type | Description |
|-------|------|-------------|
| `current` | number | Current sales total |
| `formatted` | string | Formatted for display (e.g., "$1,875.25") |
| `goal` | number | Daily sales goal |
| `goalFormatted` | string | Formatted goal |
| `variance` | number | Difference from goal (negative = under goal) |
| `varianceFormatted` | string | Formatted variance with +/- prefix |
| `comp` | number | Same day last year sales |
| `compFormatted` | string | Formatted comp value |
| `status` | string | `"good"`, `"warning"`, `"danger"`, or `"neutral"` |

### Average Transaction Object (`avgTrans`)

| Field | Type | Description |
|-------|------|-------------|
| `current` | number | Current average transaction value |
| `formatted` | string | Formatted for display |
| `goal` | number | Goal (typically 0/not set) |
| `goalFormatted` | string | Formatted goal or "--" if not set |
| `comp` | number | Same day last year average |
| `compFormatted` | string | Formatted comp value |
| `status` | string | Status indicator |

### Trade Percent Object (`tradePercent`)

Trade % = (Buys Cost / Sales) × 100. Lower is generally better.

| Field | Type | Description |
|-------|------|-------------|
| `current` | number | Current trade percentage |
| `formatted` | string | Formatted percentage (e.g., "22.69%") |
| `goal` | number | Target trade % (typically 15%) |
| `goalFormatted` | string | Formatted goal |
| `comp` | number | Same day last year trade % |
| `compFormatted` | string | Formatted comp value |
| `status` | string | `"good"` (≤12%), `"warning"` (≤15%), `"danger"` (>15%) |

### Sales & Labor Object (`salesLabor`)

| Field | Type | Description |
|-------|------|-------------|
| `transactions` | integer | Number of completed transactions today |
| `laborHours` | number | Total labor hours worked today |
| `laborHoursFormatted` | string | Formatted hours or "--" if unavailable |
| `salesPerLaborHour` | number | Sales divided by labor hours |
| `salesPerLaborHourFormatted` | string | Formatted value or "--" if unavailable |
| `totalWages` | number | Total wages paid today |
| `totalWagesFormatted` | string | Formatted wages or "--" if unavailable |

Note: Labor data requires WhenIWork integration to be enabled for the store.

### Backstock Object

| Field | Type | Description |
|-------|------|-------------|
| `pulled` | integer | Number of bins pulled from backstock today |
| `added` | integer | Number of bins added to backstock today |
| `recentActivity` | array | Last 10 backstock actions (see below) |

**Recent Activity Item:**

| Field | Type | Description |
|-------|------|-------------|
| `time` | string | Time of action (HH:MM format, store timezone) |
| `bin` | string | Bin name/identifier |
| `action` | string | Action type: `"Pulled"`, `"New Product"`, `"Emptied"`, `"Cleared Category"` |
| `category` | string | Product category name |

### Buys Object

| Field | Type | Description |
|-------|------|-------------|
| `count` | integer | Number of completed buys today |
| `countFormatted` | string | Formatted count |
| `compBuys` | number | Same day last year buys cost |
| `compBuysFormatted` | string | Formatted comp buys |
| `tradeTotal` | number | Total trade value today |
| `tradeTotalFormatted` | string | Formatted trade total |
| `percentTraded` | number | Percentage of buys that were trades |
| `percentTradedFormatted` | string | Formatted percentage |
| `compTradePercent` | number | Same day last year trade % |
| `compTradePercentFormatted` | string | Formatted comp trade % |

## Status Values

The `status` field indicates performance relative to goals:

| Status | Color | Meaning |
|--------|-------|---------|
| `good` | Green | Meeting or exceeding goal |
| `warning` | Yellow | Close to goal (90-99%) |
| `danger` | Red | Below goal (<90%) |
| `neutral` | Gray | No goal set or not applicable |

For Trade %, the logic is inverted (lower is better):
- `good`: ≤12%
- `warning`: 12-15%
- `danger`: >15%

## Usage Notes

1. **Formatted vs Raw Values**: Each metric includes both a raw numeric value and a pre-formatted string. Use the formatted values for display to ensure consistent formatting across platforms.

2. **Comp Data**: Year-over-year comparison data (`comp` fields) comes from the `closeSalesReport` table. If no data exists for the same date last year, comp values will be 0.

3. **Labor Data**: The `salesLabor` section requires WhenIWork integration. If not enabled, values will show as 0 or "--".

4. **Timezone**: All times are in the store's configured timezone.

5. **Caching**: Data is cached for 30 seconds to reduce database load. Real-time updates may have a slight delay.

## UI Mapping

This endpoint provides data for recreating the web "Today's Performance" view:

| Web Section | API Field |
|-------------|-----------|
| SALES (top left) | `sales` |
| AVG TRANS (top center) | `avgTrans` |
| TRADE % (top right) | `tradePercent` |
| Sales & Labor | `salesLabor` |
| Backstock | `backstock` |
| Buys | `buys` |