# Transaction Reports

Generate and export transaction reports.

All report endpoints are admin API calls: send `Authorization: Bearer <JWT>` (or an API key in `x-api-key`). The caller needs the `reports.view` permission. Merchant users are always confined to their own merchant; passing another merchant's `merchantId` returns `403 FORBIDDEN`. Admin users see the whole tenant unless they pass `merchantId`.

Dates are plain `YYYY-MM-DD` days. When a merchant is in scope, the days are interpreted in that merchant's timezone and converted to UTC before querying.

---

## Generate Report

```http
GET /api/v1/reports/transactions
```

```bash
curl "https://uat.auxcore.net/api/v1/reports/transactions?dateFrom=2026-01-01&dateTo=2026-01-31&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

| Query param | Notes |
|---|---|
| `dateFrom`, `dateTo` | `YYYY-MM-DD`. Both are needed for the date filter to apply. |
| `merchantId` | Admins: filter to one merchant. Merchants: optional, must be their own. |
| `branchId` | Filter to one location. |
| `transactionId`, `orderId`, `amount`, `email`, `cardLast4` | Exact-match filters. |
| `firstName`, `lastName` | Case-insensitive substring match on the customer name (applied to the returned page). |
| `page`, `limit` | Pagination. Defaults `page=1`, `limit=50`. |

**Response:**
```json
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "8d2f6a1e-3b4c-4d5e-9f60-718293a4b5c6",
        "transactionId": "TXN-1768489200000-7F3A9C21",
        "merchantId": "3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c",
        "type": "sale",
        "status": "settled",
        "amount": "125.00",
        "cardBrand": "Visa",
        "cardLast4": "4242",
        "billingCustomerName": "Jordan Lee",
        "createdAt": "2026-01-15T17:42:10.000Z"
      }
    ],
    "summary": {
      "total": 1,
      "totalAmount": 125
    }
  },
  "meta": { "page": 1, "limit": 50, "total": 1, "totalPages": 1, "summary": { }, "statusCounts": { } }
}
```

`data.summary` covers only the transactions on the returned page; `meta` (passed through from the transaction service) carries the totals and aggregates for the full filtered set. `transactions[]` items have the same shape as `GET /api/v1/transactions`.

---

## Daily Summary

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

Sales, declines, refunds, voids and chargebacks with net totals for a date range.

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

| Query param | Notes |
|---|---|
| `dateFrom`, `dateTo` | Required, `YYYY-MM-DD`. Missing → `400 VALIDATION_ERROR`. |
| `merchantId` | Admins: optional (omit for a tenant-wide aggregate). Merchants: optional, must be their own. |
| `timezone` | IANA zone; defaults to the merchant's timezone. |
| `gatewayName`, `paymentMethod`, `branchId` | Optional filters. |

Returns `data.summary` (sales / decline / refund / void / chargeback / auth-only counts and amounts, `netTransactionCount`, `netAmount`, `grossAmount`, `totalTipAmount`, `totalConvenienceFee`, `reserveFee`), `data.dailyDetails[]` (one row per day: `date`, `salesCount`, `salesAmount`, `baseAmount`, `tipAmount`, `feeAmount`, `refundCount`, `refundAmount`, `netAmount`), `data.period` and `data.generatedAt`.

---

## Export to CSV

```http
GET /api/v1/reports/export/csv
```

```bash
curl "https://uat.auxcore.net/api/v1/reports/export/csv?merchantId=3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c&dateFrom=2026-01-01&dateTo=2026-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o transactions.csv
```

| Query param | Notes |
|---|---|
| `merchantId`, `dateFrom`, `dateTo` | **Required.** Missing any → `400 VALIDATION_ERROR`. |
| `status`, `excludeStatus`, `type` | Status / type filters. |
| `paymentMethod`, `transactionGateway`, `branchId` | Optional filters. |
| `merchantIds` | Comma-separated list to export several merchants. |
| `columns` | Comma-separated column keys, in the order you want them. Defaults to the full column set. |
| `excludeSandbox`, `refundedSalesAsApproved`, `periodStatus` | `true` / `false` flags. |

Returns `text/csv` as an attachment. Failures return `500` with `EXPORT_FAILED` or `INTERNAL_ERROR`.

### Export to Excel

```http
GET /api/v1/reports/export/excel
```

Same query parameters as the CSV export; returns a formatted `.xlsx` workbook.

---

## Generic Export

```http
GET /api/v1/reports/export
```

A simpler raw export of transaction rows.

| Query param | Notes |
|---|---|
| `format` | `csv` (default) or `json`. |
| `merchantId`, `dateFrom`, `dateTo`, `status` | Optional filters. Non-admin users are limited to their own merchant. |
| `limit` | Default `5000`. |
| `type` | Only changes the download file name; the rows are always transactions. |

CSV columns: `id, transactionId, merchantId, type, status, amount, baseAmount, tipAmount, convenienceFee, paymentMethod, cardLast4, cardBrand, gatewayName, gatewayTransactionId, currency, notes, createdAt, settledAt`. With `format=json` the body is `{ "success": true, "count": 2, "data": [ ... ] }`.

---

## Email Report

> **Note:** there is no API endpoint for emailing a transaction report. Download it with one of the export endpoints above. Funding reports can be emailed — see Funding Reports.

---

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