# Revenue & Financial Performance Reports API — Admin Dashboard

Read-only reports for the admin "Reports" screen (BRD §13 "التقارير" — "إجمالي المدفوعات حسب الفترة" / "طلبات الكتب الورقية وحالاتها"): revenue and payment analytics across courses, programs, consultations and the book store, plus a dedicated book-orders report and a payment-ledger drill-down. Build one "Revenue" screen (summary cards + chart + breakdown tables) and one "Orders" screen on top of these three endpoints.

- **Base path:** `{{base_url}}/admin` (e.g. `http://localhost:8000/api/v1/admin`)
- **Auth:** `Authorization: Bearer {{admin_token}}` on every request
- **Middleware stack:** `api, set_locale, cors, auth:api, active, rbac.auto`
- **RBAC permissions:** `reports.revenue`, `reports.transactions`, `reports.orders` (seeded by `PermissionSeeder`; super admins pass automatically, other roles must be granted them)
- **Source files:**
  - Controller: [ReportController.php](../../app/Http/Controllers/Api/V1/Admin/ReportController.php)
  - Service: [RevenueReportService.php](../../app/Services/Admin/RevenueReportService.php)
  - Request: [RevenueReportRequest.php](../../app/Http/Requests/Admin/Report/RevenueReportRequest.php)
  - Tests: [RevenueReportTest.php](../../tests/Feature/Admin/RevenueReportTest.php)

Sibling doc: [reports-admin.md](./reports-admin.md) covers the attendance/completion reports (`/admin/reports/courses`, `/admin/reports/programs`) — unrelated data, same "Reports" screen family.

---

## The one rule that matters most: revenue = successful payments only

Every "revenue" figure in this API (`summary`, `series`, `by_source`, `by_payment_method`, `by_trainer`, `top_items`) is computed **only from payments with `status = "success"`**. Pending and failed payments never contribute to a revenue number — they only appear in `overview` and `by_status`, which report attempts, not money collected. If a number here looks lower than "total checkouts started," that's why — check `overview.pending` / `overview.failed`.

The one exception is the **Orders report** (`GET /admin/reports/orders`): it counts **orders**, not payments, and is not filtered by payment status at all (see [that section](#get-adminreportsorders) for why).

---

## Endpoints at a glance

| Screen | Method | Endpoint | Purpose |
|---|---|---|---|
| Revenue | `GET` | `{{base_url}}/admin/reports/revenue` | Full revenue report: summary, trend, breakdowns, top items |
| Revenue → drill-down | `GET` | `{{base_url}}/admin/reports/revenue/transactions` | Paginated payment ledger behind the totals |
| Orders | `GET` | `{{base_url}}/admin/reports/orders` | Book-order counts, statuses, physical/digital split, delivery time |

All three accept the same shared query parameters (below); each endpoint only uses the ones relevant to it.

---

## Query parameters

All optional. Send only the ones the user has actually set — omitting a filter is how you get the unfiltered report, not `null`/`""`.

| Param | Type | Used by | Description |
|---|---|---|---|
| `from` | `Y-m-d` | revenue, orders, transactions | Period start (inclusive, from `00:00:00`) |
| `to` | `Y-m-d` | revenue, orders, transactions | Period end (inclusive, through `23:59:59`). Must be `>= from` or the request is rejected |
| `preset` | `today` \| `this_month` \| `last_month` \| `this_year` | revenue, orders, transactions | Convenience period; ignored if `from` or `to` is sent — see [Period resolution](#period-resolution) |
| `group_by` | `day` \| `month` | revenue, orders | Trend bucket for `series` (revenue) or `trend` (orders, only computed with `include_trend=1`). Auto-chosen when omitted — see below |
| `include_trend` | `0` \| `1` | orders only | Default `0`. `1` adds `data.trend`, the per-bucket Total/Processing/Delivered series — see [`GET /admin/reports/orders`](#get-adminreportsorders) below. `revenue` always returns its `series`; it has no `include_trend` flag |
| `source` | `course` \| `program` \| `consultation` \| `physical_book` \| `digital_book` | revenue, orders, transactions | Restrict to one revenue source (`physical_book`/`digital_book` map to `orders.type` on the Orders report) |
| `payment_method` | string | revenue, transactions | Exact match on `payments.payment_method` — whatever string the checkout screen sent (e.g. `card`, `wallet`); there is no fixed enum, so populate a filter dropdown from `by_payment_method` in a first call, not from a hardcoded list |
| `country_id` | uuid | revenue, orders, transactions | Restrict to payments/orders priced in this country's currency (the country tied to `currency_country_id`, **not** the buyer's profile country) |
| `trainer_id` | uuid | revenue, transactions | Restrict to courses/programs/consultations owned by this trainer. ⚠️ Books have no trainer — setting this filter drops all book/order revenue from every section, not just `by_trainer` |
| `status` | `success` \| `failed` \| `pending` | transactions only | Filter the ledger by payment status. Ignored by `revenue`/`orders`, which always show all statuses split out separately |
| `search` | string, max 100 | transactions only | Matches `transaction_reference`, the buyer's full name, or their email |
| `page` | integer | transactions only | Page number, default `1` |
| `per_page` | integer | transactions only | Rows per page, default `15`, clamped to `1–100` |

### Period resolution

1. If `from` and/or `to` is present, they win — `preset` is ignored.
   - `to` alone → `from` defaults to the **start of the month containing `to`**, not "30 days back."
   - `from` alone → `to` defaults to today.
2. Otherwise `preset` applies (`today`, `this_month`, `last_month`, `this_year`).
3. With neither, the report defaults to **`this_month`**.

The resolved range is always echoed back in the response under `period`, so render the active range from the response rather than re-deriving it client-side.

### `group_by` auto-selection

When `group_by` is omitted, `revenue` picks `day` for a range of 62 days or less, and `month` for anything longer. `period.group_by` in the response tells you which one was actually used.

### Daily-range cap

`group_by=day` is rejected with a `422` when `to − from` exceeds **366 days** (send `group_by=month` for long ranges, or omit it and let auto-selection handle it).

---

## `GET /admin/reports/revenue`

### Response shape

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "period": {
      "from": "2026-09-01",
      "to": "2026-09-22",
      "group_by": "day"
    },
    "summary": [
      {
        "currency": { "id": "6f1e...-country-uuid", "code": "EGP", "symbol": "E£" },
        "gross_revenue": 12500.00,
        "shipping_fees": 340.00,
        "items_revenue": 12160.00,
        "payments_count": 84,
        "average_payment": 148.81,
        "previous_period": { "gross_revenue": 9800.00, "payments_count": 61 },
        "change_percent": 27.55
      },
      {
        "currency": { "id": "a02c...-country-uuid", "code": "SAR", "symbol": "SR" },
        "gross_revenue": 3200.00,
        "shipping_fees": 0.00,
        "items_revenue": 3200.00,
        "payments_count": 15,
        "average_payment": 213.33,
        "previous_period": { "gross_revenue": 0.00, "payments_count": 0 },
        "change_percent": null
      }
    ],
    "overview": {
      "total_attempts": 112,
      "successful": 99,
      "pending": 6,
      "failed": 7,
      "success_rate": 88.39
    },
    "series": [
      {
        "period": "2026-09-01",
        "values": [
          { "currency": { "id": "6f1e...", "code": "EGP", "symbol": "E£" }, "revenue": 0.00, "payments_count": 0 },
          { "currency": { "id": "a02c...", "code": "SAR", "symbol": "SR" }, "revenue": 0.00, "payments_count": 0 }
        ]
      },
      {
        "period": "2026-09-02",
        "values": [
          { "currency": { "id": "6f1e...", "code": "EGP", "symbol": "E£" }, "revenue": 850.00, "payments_count": 5 },
          { "currency": { "id": "a02c...", "code": "SAR", "symbol": "SR" }, "revenue": 0.00, "payments_count": 0 }
        ]
      }
    ],
    "by_source": [
      { "source": "course", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 6200.00, "payments_count": 40, "share_percent": 49.60 },
      { "source": "program", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 3100.00, "payments_count": 12, "share_percent": 24.80 },
      { "source": "consultation", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 1900.00, "payments_count": 19, "share_percent": 15.20 },
      { "source": "physical_book", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 1300.00, "payments_count": 13, "share_percent": 10.40 }
    ],
    "by_payment_method": [
      { "payment_method": "card", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 9800.00, "payments_count": 66 },
      { "payment_method": "wallet", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 2700.00, "payments_count": 18 }
    ],
    "by_status": [
      { "status": "success", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "amount": 12500.00, "payments_count": 84 },
      { "status": "pending", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "amount": 640.00, "payments_count": 6 },
      { "status": "failed", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "amount": 910.00, "payments_count": 7 }
    ],
    "by_trainer": [
      { "trainer_id": "b3aa...-trainer-uuid", "trainer": "Sara Al-Mansouri", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 5400.00, "payments_count": 28 }
    ],
    "top_items": {
      "courses": [
        { "id": "00000000-0000-0000-0000-000000000001", "name": "Financial Management Essentials", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 2400.00, "payments_count": 16 }
      ],
      "programs": [
        { "id": "00000000-0000-0000-0000-000000000002", "name": "Leadership Track", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 3100.00, "payments_count": 12 }
      ],
      "consultations": [
        { "id": "00000000-0000-0000-0000-000000000003", "name": "Tax Consultations — Sara Al-Mansouri", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 1000.00, "payments_count": 10 }
      ],
      "books": [
        { "id": "00000000-0000-0000-0000-000000000004", "name": "Advanced Bookkeeping", "currency": { "code": "EGP", "symbol": "E£", "id": "6f1e..." }, "revenue": 900.00, "units": 18 }
      ]
    }
  }
}
```

### Field reference

#### `summary[]` — one row per currency

| Field | Type | Meaning |
|---|---|---|
| `currency` | object | `{ id (country uuid), code, symbol }` — the currency this row's figures are in. Every money field across the whole response is namespaced by this same object; **never sum across currency rows** |
| `gross_revenue` | number | Sum of `payments.total_amount` for successful payments in the period (includes shipping) |
| `shipping_fees` | number | Sum of `payments.shipping_fee` — the shipping portion of `gross_revenue` |
| `items_revenue` | number | `gross_revenue − shipping_fees` — revenue excluding shipping |
| `payments_count` | integer | Number of successful payments |
| `average_payment` | number | `gross_revenue / payments_count`; `0` when `payments_count` is `0` |
| `previous_period` | object | `{ gross_revenue, payments_count }` for the immediately preceding period of equal length (e.g. a 22-day range compares to the 22 days right before `from`) |
| `change_percent` | number \| `null` | `(gross_revenue − previous.gross_revenue) / previous.gross_revenue × 100`, 2 decimals. **`null`** when the previous period had zero revenue (division by zero, not "0% change") — render this as "New" or "—", never as `0%` |

A currency can appear in `summary` with `gross_revenue: 0` if it only had revenue in the *previous* period (so the comparison card still renders). A currency with revenue in neither period never appears at all.

#### `overview` — payment attempts, not money

| Field | Type | Meaning |
|---|---|---|
| `total_attempts` | integer | All payment rows in the period, any status, any currency |
| `successful` / `pending` / `failed` | integer | Same, split by status |
| `success_rate` | number | `successful / total_attempts × 100`, 2 decimals; `0` when there were no attempts |

This block is currency-agnostic (counts, not amounts) — use it for one "success rate" KPI tile regardless of how many currencies are active.

#### `series[]` — the trend chart

One entry per `period` bucket (`Y-m-d` or `Y-m` depending on `period.group_by`), covering the **entire requested range with no gaps** — a day/month with zero successful payments still appears, with `revenue: 0`. Each entry's `values[]` has exactly one row per currency that appeared anywhere in `summary`, in the same order, so `series[i].values[j]` and `summary[j]` always refer to the same currency — index-align them when building a multi-currency chart, or key off `values[j].currency.code`.

#### `by_source[]`, `by_payment_method[]`, `by_status[]`, `by_trainer[]`

Flat breakdown lists, one row per (dimension value × currency), sorted by revenue/amount descending (except `by_status`, which is unsorted — render it in a fixed `success → pending → failed` order client-side). `share_percent` in `by_source` is that row's revenue as a percentage of *all* revenue **in that same currency** (not the grand total across currencies).

`by_trainer` only includes trainers with at least one successful payment on a course, program, or consultation they own — book revenue is never attributed to a trainer. Limited to the top 10 by revenue.

#### `top_items`

Four independently-ranked top-10 lists (`courses`, `programs`, `consultations`, `books`), each already sorted by revenue descending. `id` is the item's public uuid (deep-link to its admin detail page). A `consultations` row's `name` is `"{consultation type} — {trainer name}"` (either half may be missing).

⚠️ **`top_items.books` is not directly comparable to `by_source`'s book rows.** Top books revenue is summed from `order_items.line_total` (the book's line price only, no shipping, and attributed per book even when several books share one order); `by_source`'s `physical_book`/`digital_book` revenue is summed from `payments.total_amount` (the whole payment, shipping included). Don't subtract one from the other expecting it to reconcile — use `by_source` for the money total and `top_items.books` for "what sold," with its own `units` count.

---

## `GET /admin/reports/orders`

Unlike every other section on this page, this endpoint reports on the **`orders` table directly** — it is not filtered by payment status and does not require a successful payment to count. Rationale: BRD §13 asks to track "طلبات الكتب الورقية وحالاتها" (physical book orders and their statuses), which includes orders still `processing`, independent of whether their payment has settled yet. If you need "book revenue actually collected," use `by_source` / `top_items.books` on the revenue endpoint instead — this endpoint answers "how many orders, in what state," not "how much money."

`source` here filters `orders.type` (`physical_book` → `type=physical`, `digital_book` → `type=digital`); `payment_method`, `trainer_id` and `status` are not applicable and are silently ignored. Passing a non-book `source` (`course`/`program`/`consultation`) is not an error — the Orders report only ever holds books, so it simply returns an empty report (`orders_count: 0`).

### Response shape

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "period": { "from": "2026-09-01", "to": "2026-09-22" },
    "orders_count": 34,
    "status_totals": { "processing": 9, "delivered": 25 },
    "by_status_and_type": [
      {
        "status": "processing",
        "type": "physical",
        "orders_count": 9,
        "total_value": 1080.00,
        "shipping_fees": 180.00,
        "currency": { "id": "6f1e...", "code": "EGP", "symbol": "E£" }
      },
      {
        "status": "delivered",
        "type": "physical",
        "orders_count": 20,
        "total_value": 2400.00,
        "shipping_fees": 400.00,
        "currency": { "id": "6f1e...", "code": "EGP", "symbol": "E£" }
      },
      {
        "status": "delivered",
        "type": "digital",
        "orders_count": 5,
        "total_value": 500.00,
        "shipping_fees": 0.00,
        "currency": { "id": "6f1e...", "code": "EGP", "symbol": "E£" }
      }
    ],
    "average_delivery_hours": 46.2
  }
}
```

| Field | Type | Meaning |
|---|---|---|
| `orders_count` | integer | Total orders in the period, all statuses/types/currencies |
| `status_totals` | object | `{ processing, delivered }` order counts, summed across type and currency — a quick KPI pair regardless of multi-currency |
| `by_status_and_type[]` | array | One row per (status × type × currency); `total_value` is `orders.total_price`, `shipping_fees` is `orders.shipping_price` (always `0` for digital orders) |
| `average_delivery_hours` | number \| `null` | Mean hours between `created_at` and `delivered_at` for **physical** orders that have been delivered. `null` when none have (nothing to average) — render "—", not "0h" |

Digital orders are marked `delivered` immediately on purchase (no shipping step), so they always contribute `0` toward `average_delivery_hours`'s denominator — hence the calculation excludes them explicitly rather than skewing the average toward zero.

### Dated trend (`include_trend=1`)

```json
{
  "data": {
    "period": { "from": "2026-09-01", "to": "2026-09-03", "group_by": "day", "timezone": "UTC" },
    "orders_count": 3,
    "status_totals": { "processing": 2, "delivered": 1 },
    "trend": [
      { "period": "2026-09-01", "orders_count": 1, "processing": 1, "delivered": 0 },
      { "period": "2026-09-02", "orders_count": 2, "processing": 1, "delivered": 1 },
      { "period": "2026-09-03", "orders_count": 0, "processing": 0, "delivered": 0 }
    ]
  }
}
```

With `include_trend=1`, `period` also carries `group_by`/`timezone`, and `data.trend` adds a zero-filled per-bucket series for the Total/Processing/Delivered cards. Every bucket buckets by `orders.created_at` (when the order was placed) — `processing`/`delivered` split those same orders by their **current** status, not by when a status change happened, so an order placed on day 1 and delivered on day 3 still counts under `delivered` in day 1's bucket, not day 3's. `sum(trend[].orders_count) === orders_count`, and likewise for `processing`/`delivered` against `status_totals`. `trend` is omitted when `include_trend` is `0` or absent.

---

## `GET /admin/reports/revenue/transactions`

The drill-down behind every total on the revenue report — a searchable, filterable, paginated payment ledger. Standard Laravel paginator envelope, same shape as [reports-admin.md](./reports-admin.md)'s tables.

### Response shape

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 4821,
        "user": { "id": "c9a1...-user-uuid", "name": "Mona Farouk" },
        "source": "course",
        "item": "Financial Management Essentials",
        "payment_method": "card",
        "amount": 150.00,
        "shipping_fee": 0.00,
        "total_amount": 150.00,
        "currency": { "id": "6f1e...", "code": "EGP", "symbol": "E£" },
        "status": "success",
        "transaction_reference": "TXN-8823410A",
        "paid_at": "2026-09-14T10:32:05+00:00",
        "created_at": "2026-09-14T10:31:58+00:00"
      },
      {
        "id": 4790,
        "user": { "id": "77bd...-user-uuid", "name": "Omar Khaled" },
        "source": "physical_book",
        "item": "Advanced Bookkeeping, Tax Planning 101",
        "payment_method": "wallet",
        "amount": 100.00,
        "shipping_fee": 20.00,
        "total_amount": 120.00,
        "currency": { "id": "6f1e...", "code": "EGP", "symbol": "E£" },
        "status": "failed",
        "transaction_reference": "TXN-661102FF",
        "paid_at": null,
        "created_at": "2026-09-11T08:02:11+00:00"
      }
    ],
    "per_page": 15,
    "total": 2,
    "last_page": 1,
    "from": 1,
    "to": 2,
    "next_page_url": null,
    "prev_page_url": null
  }
}
```

### Row fields

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Internal payment id — **not a uuid** (payments have no public uuid in this schema); fine to use as a React `key`, not as a deep-link param |
| `user` | object | `{ id (user uuid), name }`. In practice always present — deleting a user cascades to their payments, so a payment row never outlives its buyer — but code defensively (`user?.name ?? "—"`) rather than assuming it |
| `source` | string | `course` \| `program` \| `consultation` \| `physical_book` \| `digital_book` \| `other`. `other` should not occur in practice (every payment must reference exactly one of enrollment/consultation booking/order per the schema's check) — treat it as a data-integrity signal if seen |
| `item` | string \| null | Human-readable label: the course/program name, the consultation type name, or a comma-joined list of book titles for an order. Courses/programs/books can't normally be deleted while a payment references them, so this is effectively always present — but code defensively, as `null` is possible in edge cases |
| `payment_method` | string \| null | Raw value as sent at checkout |
| `amount` | number | `payments.amount` (before shipping) |
| `shipping_fee` | number | `payments.shipping_fee` |
| `total_amount` | number | `amount + shipping_fee` — what the customer was actually charged |
| `currency` | object | `{ id, code, symbol }`, can be all-`null` if the payment has no `currency_country_id` |
| `status` | string | `success` \| `pending` \| `failed` |
| `transaction_reference` | string \| null | Gateway reference, if the integration returned one |
| `paid_at` | ISO 8601 string \| null | `null` for `pending`/`failed` payments |
| `created_at` | ISO 8601 string | When the payment row was created (checkout time) |

Rows are sorted by `paid_at` (falling back to `created_at` for pending/failed rows) descending, then by `id` descending as a tiebreaker.

---

## Frontend notes

1. **Never sum money across `currency` blocks.** Every list in this API is currency-partitioned; a dashboard with mixed-currency data needs either separate currency tabs or per-currency stat cards, not a single blended total.
2. **`change_percent: null` means "no baseline," not "no change."** Show "New" or "—"; a literal `0%` would misreport a currency that only started generating revenue this period.
3. **Zero-filled `series`.** No client-side gap-filling or date-bucketing is needed — iterate `series` directly for the chart x-axis.
4. **`group_by` is a suggestion, not a fixed setting.** If the user didn't pick one, read `period.group_by` from the response to label the chart correctly ("Daily" vs "Monthly") — don't assume `day`.
5. **Filters reset paging.** On the transactions ledger, changing any filter should reset to `page=1`.
6. **Debounce `search`** (300 ms) on the transactions screen — it runs a `LIKE` query per keystroke-triggered request.
7. **The Orders report is payment-status-agnostic by design** — see the callout above. Don't wire its `orders_count`/`status_totals` into the same KPI row as `overview.successful` from the revenue endpoint; they answer different questions.
8. **`trainer_id` silently zeroes out book data.** If a trainer filter is active, hide (or grey out) the book-related rows/cards instead of showing a confusing `0`/empty state that looks like "no book sales."
9. **Populate the `payment_method` filter dropdown from data, not a hardcoded list** — call `GET /admin/reports/revenue` once (or reuse the last response) and build the dropdown from `by_payment_method[].payment_method`, since the backend accepts whatever string checkout sent.
10. **`country_id` filters by pricing currency, not buyer geography.** A Saudi-registered user who bought a course priced in EGP will show up under the EGP filter, not SAR.
11. **Permissions in the UI.** Hide the Revenue tab when the admin lacks `reports.revenue` (and the transactions drill-down when lacking `reports.transactions`); hide the Orders tab when lacking `reports.orders`. A missing permission returns `403` with an `X-Missing-Permission` header naming it.
12. **Rates/amounts are numbers, not strings.** A whole value serialises as `0`, not `"0.00"` — format with your own decimal rules.

---

## Error codes

| HTTP Status | Trigger |
|---|---|
| `401 Unauthorized` | Missing or expired admin bearer token |
| `403 Forbidden` | Admin role lacks `reports.revenue` / `reports.transactions` / `reports.orders` |
| `422 Unprocessable Entity` | `to` before `from`; `from`/`to` not `Y-m-d`; `group_by=day` on a range over 366 days; `source`/`preset`/`status`/`group_by` outside their allowed values |

An unmatched `country_id`, `trainer_id`, or `search` term is not an error — it simply returns empty sections / an empty ledger page, `total: 0`.

---

## Example requests

```bash
# This month's revenue report (default period), default day/month grouping
curl -H "Authorization: Bearer {{admin_token}}" \
  "{{base_url}}/admin/reports/revenue"

# Custom range, forced monthly grouping, one trainer only
curl -H "Authorization: Bearer {{admin_token}}" \
  "{{base_url}}/admin/reports/revenue?from=2026-01-01&to=2026-09-22&group_by=month&trainer_id={{trainer_id}}"

# Book revenue only, one currency
curl -H "Authorization: Bearer {{admin_token}}" \
  "{{base_url}}/admin/reports/revenue?source=physical_book&country_id={{country_id}}"

# This quarter's book orders, digital only
curl -H "Authorization: Bearer {{admin_token}}" \
  "{{base_url}}/admin/reports/orders?from=2026-07-01&to=2026-09-22&source=digital_book"

# Failed payments matching a reference or buyer name/email, page 2
curl -H "Authorization: Bearer {{admin_token}}" \
  "{{base_url}}/admin/reports/revenue/transactions?status=failed&search=TXN-88&page=2"
```

Postman: see "Revenue Report", "Transactions Report" and "Orders Report" in [admin.md](./admin.md#revenue-report).

---

## Not included (yet)

- Certificates-issued and average-rating reports (BRD §13 also lists these; no endpoint exists yet)
- Currency conversion / a blended cross-currency total
- CSV / Excel export
- Refunds (the schema has no refund status on `payments`)
