# Analytics

Track payment performance and business metrics.

> **Note:** there is no `/api/v1/analytics/*` API. Payment analytics are served by the dashboard summary and the reporting endpoints below. Revenue grouping, fraud analytics and subscription analytics are not available via the API.

All endpoints are admin API calls: send `Authorization: Bearer <JWT>` (or an API key in `x-api-key`). The tenant comes from the token or key.

---

## Dashboard Summary

```http
GET /api/v1/dashboard/summary
```

```bash
curl "https://uat.auxcore.net/api/v1/dashboard/summary?merchantId=3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c&dateRange=custom&dateFrom=2026-08-01&dateTo=2026-08-31" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

| Query param | Notes |
|---|---|
| `merchantId` | Optional. Merchant users default to their own merchant; tenant admins omitting it get a tenant-wide summary. |
| `dateRange` | `today`, `yesterday`, `this_week`, `last_week`, `last_7_days`, `last_30_days`, `this_month` (default), `last_month`, `mtd`, `qtd`, `ytd`, `all`, `custom`. Unknown values fall back to `this_month`. |
| `dateFrom`, `dateTo` | `YYYY-MM-DD`. Only used when `dateRange=custom` (both required). |
| `timezone` | IANA zone. Defaults to the merchant's timezone, else `America/New_York`. |

**Response:**
```json
{
  "success": true,
  "data": {
    "currentDayTotal": 1240.5,
    "currentDayTransactionCount": 8,
    "currentMonthTotal": 48210.75,
    "currentMonthTransactionCount": 312,
    "currentYearTotal": 402118.2,
    "currentYearTransactionCount": 2874,
    "customerCount": 143,
    "realTimeData": { "totalAmount": 1610, "transactionCount": 11 },
    "settlementData": { "totalAmount": 1240.5, "transactionCount": 8 },
    "dailyTransactions": [
      { "day": "2026-08-01", "dayName": "Saturday", "totalAmount": 2210, "transactionCount": 14 }
    ],
    "period": { "from": "2026-08-01T04:00:00.000Z", "to": "2026-09-01T03:59:59.999Z", "timezone": "America/New_York" },
    "chart": { "granularity": "day", "timezone": "America/New_York", "from": "2026-08-01", "to": "2026-08-31", "complete": true },
    "statusDistribution": { "settled": 298, "declined": 11, "voided": 3 },
    "periodTotal": 48210.75,
    "periodTransactionCount": 312,
    "averageTicket": 154.52,
    "refundTotalAmount": 320,
    "refundCount": 2,
    "voidTotalAmount": 75,
    "voidCount": 3,
    "chargebackTotalAmount": 0,
    "chargebackCount": 0,
    "totalCardTrans": 281,
    "totalAchTrans": 24,
    "totalCashTrans": 7,
    "paymentChannelBreakdown": { "card": 43100.25, "ach": 3610.5, "terminal": 0, "links": 1500 },
    "periodComparison": {
      "label": "prior period",
      "salesTotal": 45102.1,
      "transactionCount": 298,
      "averageTicket": 151.35,
      "approvalRate": 96.4,
      "declinedCount": 11
    }
  }
}
```

`periodTotal`, `averageTicket`, `dailyTransactions`, `statusDistribution` and the refund/void/chargeback figures follow `dateRange`; the `currentDay*`, `currentMonth*` and `currentYear*` figures always use today, this month and this year. `paymentChannelBreakdown` values are sales **amounts** per channel, while `totalCardTrans` / `totalAchTrans` / `totalCashTrans` are counts. `chart` describes the `dailyTransactions` buckets (`granularity` is `hour` for single-day ranges, with `hour`, `fromHour`, `toHour`). `periodComparison` is only computed for `today` (vs yesterday), `this_week`, `this_month`, `mtd` (vs last month), `last_7_days` / `last_30_days` (vs the preceding 7 / 30 days) and `custom` (vs the prior period of equal length); for other ranges it is `null`. For several merchants at once, see Multi-Merchant Dashboard Summary.

---

## Daily Summary Report

```http
GET /api/v1/reports/daily-summary
```

Sales, declines, refunds, voids and chargebacks with net totals. Requires `dateFrom` and `dateTo` (`YYYY-MM-DD`); optional `merchantId`, `timezone`, `gatewayName`, `paymentMethod`, `branchId`. See Transaction Reports for details.

---

## Card Brand Breakdown

```http
GET /api/v1/reports/card-aggregate
```

Transaction totals grouped by card brand for a date range: `dateFrom` and `dateTo` required (else `400 VALIDATION_ERROR`); optional `merchantId`, `transactionGateway`, `branchId`.

---

## Other Report Endpoints

All require the `reports.view` permission:

| Endpoint | Purpose |
|---|---|
| `GET /api/v1/reports/tip-report` | Tips by customer. `merchantId`, `dateFrom`, `dateTo` required. |
| `GET /api/v1/reports/fees` | Fee breakdown. `dateFrom`, `dateTo` required; admins must also pass `merchantId`. |
| `GET /api/v1/reports/settlements/summary` | Settlement totals. `dateFrom`, `dateTo` required. |
| `GET /api/v1/reports/payouts/summary` | Payout totals. `dateFrom`, `dateTo` required. |
| `GET /api/v1/reports/reserves/:merchantId` | Reserve report for a merchant. |
| `GET /api/v1/reports/merchant-performance/:merchantId` | Performance metrics for a merchant. `dateFrom`, `dateTo` required. |
| `GET /api/v1/reports/discrepancies` | Settlement discrepancies (`status`: `new`, `investigating`, `resolved`, `accepted`). |

> **Known issue:** the settlement-backed reports (`settlements/summary`, `payouts/summary`, `reserves/:merchantId`, `merchant-performance/:merchantId`, `discrepancies`) currently return `500 INTERNAL_ERROR`. Use the settlement endpoints directly (`GET /api/v1/settlements`, `GET /api/v1/settlements/funding-report`) until they are fixed.

---

**Need help?** Contact support@auxcore.net