> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Dashboard — Orders and fulfilment

Source: `modules/Orders/Routes/api.php` on `main`. All routes require `auth:sanctum` and localized order errors.

| Method | Endpoint | Required permission |
|---|---|---|
| GET | `/admin/orders/settings` | `settings.manage` |
| PATCH | `/admin/orders/settings` | `settings.manage` |
| GET | `/admin/orders/settings/history` | `settings.manage` |
| GET | `/admin/orders/delivery-board` | `orders.view` |
| GET | `/admin/orders/cancel-requests` | `orders.view` |
| GET | `/admin/orders/cancel-requests/{requestRef}` | `orders.view` |
| GET | `/admin/orders/` | `orders.view` |
| GET | `/admin/orders/{ref}` | `orders.view` |
| GET | `/admin/orders/{ref}/history` | `orders.view` |
| GET | `/admin/orders/{ref}/audit` | `orders.view` |
| GET | `/admin/orders/{ref}/receipt` | `orders.view` |
| POST | `/admin/orders/{ref}/release-hold` | `orders.holds.release` |
| POST | `/admin/orders/{ref}/recheck-payment` | `orders.payments.recheck` |
| POST | `/admin/orders/{ref}/picked-up` | `orders.delivery.update` |
| POST | `/admin/orders/{ref}/shipped` | `orders.delivery.update` |
| POST | `/admin/orders/{ref}/courier-arrived` | `orders.delivery.update` |
| POST | `/admin/orders/{ref}/delivery-failed` | `orders.delivery.update` |
| POST | `/admin/orders/{ref}/return-verified` | `orders.delivery.update` |
| POST | `/admin/orders/{ref}/handed-over` | `orders.delivery.update` |
| POST | `/admin/orders/{ref}/complete` | `orders.complete` |
| POST | `/admin/orders/{ref}/cancel` | `orders.cancel` |
| POST | `/admin/orders/{ref}/return-charge/settle` | `orders.return_charge.settle` |
| POST | `/admin/orders/{ref}/return-charge/waive` | `orders.return_charge.waive` |
| POST | `/admin/orders/cancel-requests/{requestRef}/approve` | `orders.cancel_requests.decide` |
| POST | `/admin/orders/cancel-requests/{requestRef}/reject` | `orders.cancel_requests.decide` |

`{ref}` is `[A-Za-z]{3}-\d{4,12}`; `{requestRef}` is `[A-Za-z]{2}-\d{1,12}`. The source-reviewed request and response contracts are documented in the sections below. These are **static code findings, not Staging test results**; runtime error envelopes and integration outcomes still require verification.

---

## Source-verified contract expansion — Orders list, detail, audit and admin actions (2026-11-22)

**Base URL:** `/api/v1`. All routes in this file require `Authorization: Bearer <token>` (`auth:sanctum`); `LocalizeOrderErrors` localizes business errors. Permission checks are enforced by middleware, not merely by the UI. Sources: [`OrderAdminController.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Interfaces/Http/Controllers/Admin/OrderAdminController.php), [`AdminOrderPresenter.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Interfaces/Http/Presenters/AdminOrderPresenter.php), [`OrderListFilters.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Infrastructure/ReadModel/OrderListFilters.php), and the corresponding `Requests` files. This section is verified against source, **not** against a running API.

### GET `/admin/orders` — paginated admin list

Permission: `orders.view`. Default sort `-placed_at`; default `per_page=20`, allowed `1..100`. Standard Spatie query syntax: `filter[field]=value` and `sort=-field` (prefix `-` for descending).

| Query parameter | Type / validation | Meaning |
|---|---|---|
| `per_page` | integer, 1..100 | Page size; default 20 |
| `page` | integer | Laravel pagination page |
| `sort` | enum field, optional `-` prefix | `placed_at`, `paid_at`, `buyer_total`, `items_total`, `commission`, `id`, `status`, `hold_expires_at`, `picked_up_at`, `arrived_at`, `auto_complete_at`, `completed_at`, `cancelled_at` |
| `filter[status]` | comma-separated statuses | Order statuses; `refunded` also matches payment status `refunded` |
| `filter[payment_status]` | comma-separated statuses | Payment state |
| `filter[delivery_method]` | comma-separated values | Delivery type |
| `filter[cancel_reason]`, `filter[refund_case]`, `filter[commission_state]`, `filter[completed_by]` | string / comma list | Domain-specific states |
| `filter[buyer_id]`, `filter[seller_id]`, `filter[city_id]`, `filter[product_id]` | numeric ID or comma list | Entity filters |
| `filter[ref]` | string | Exact order reference (normalized to uppercase) |
| `filter[search]` | string | Reference, buyer/seller matching and numeric reference lookup |
| `filter[amount_min]`, `filter[amount_max]` | decimal, up to 9 digits + 2 decimal places | Buyer total inclusive range |
| `filter[placed_from]`, `filter[placed_to]`, `filter[paid_from]`, `filter[paid_to]` | date | Date ranges |
| `filter[completed_from]`, `filter[completed_to]`, `filter[cancelled_from]`, `filter[cancelled_to]` | date | Date ranges |
| `filter[hold_live]`, `filter[needs_attention]`, `filter[disputed]`, `filter[return_charge_outstanding]` | boolean-like (`true`/`false`) | Operational flags |
| `filter[overdue]`, `filter[failed]`, `filter[delivery_issue]`, `filter[awaiting_confirmation]`, `filter[auto_complete_due]`, `filter[picked_up]` | boolean-like | Fulfilment flags |
| `filter[picked_up_from]`, `filter[picked_up_to]`, `filter[arrived_from]`, `filter[arrived_to]` | date | Fulfilment date ranges |

**Example:** `GET /api/v1/admin/orders?filter[status]=paid,preparing&filter[search]=OUT-0012&sort=-placed_at&per_page=20&page=1` (illustrative values).

**Response:** top-level JSON object (not an `ApiResponse::ok` wrapper), with `data: AdminOrderRow[]`, `links: {first,last,prev,next}`, `meta: {current_page,from,last_page,per_page,to,total,statuses,status_keys,commission_states,payment_statuses,delivery_methods,cancel_reasons,refund_cases,sorts}`. Each `meta` labels collection is generated from domain enums and enabled locales. Do not hardcode dropdown options in the dashboard. The row presenter includes `id`, `ref`, `status`, `status_key`, `status_label` (locale map), `payment_status`, `payment_status_label`, `payment_failure`, `cancel_reason`, `cancel_reason_label`, `dispute_ref`, `refund_total` and additional financial/people/fulfilment fields; bind unknown fields defensively until a full presenter schema review.

```json
{
  "data": [],
  "links": {"first": "https://example.test/api/v1/admin/orders?page=1", "last": "https://example.test/api/v1/admin/orders?page=1", "prev": null, "next": null},
  "meta": {"current_page": 1, "from": null, "last_page": 1, "per_page": 20, "to": null, "total": 0, "statuses": [], "status_keys": [], "commission_states": [], "payment_statuses": [], "delivery_methods": [], "cancel_reasons": [], "refund_cases": [], "sorts": []}
}
```

Example URLs are placeholders; actual enum metadata arrays are populated by the server.

### GET `/admin/orders/{ref}` — order detail

Permission: `orders.view`. `{ref}` route regex `[A-Za-z]{3}-\d{4,12}`; lookup uppercases and trims. Missing order yields `OrderNotFound` (localized error). `ApiResponse::ok` returns a data object containing the `AdminOrderPresenter::detail` row and:

| Response field | Type | Notes |
|---|---|---|
| `items` | array | `product_id`, `name`, `cover_image_url`, `size`, `condition`, `price`, `old_price`, `links.product` |
| `snapshot` | object | Fixed order money snapshot: currency, item total, service/delivery fees, buyer total, commission, seller net, tax details |
| `address`, `pickup` | object/null | Stored order data |
| `status_history` | array | Ordered status transitions with actor and timestamp |
| `actions` | object of booleans | `release_hold`, `recheck_payment`; depends on status **and** admin permission |
| `fulfilment_actions` | object of booleans | Server-calculated eligibility for all fulfilment buttons |
| `delivery` | object | Milestone times, shipment, proof photos, delivery issue, return cause |
| `payment` | object | `reference`, `state`, `attempts`, `can_retry`, `paid_attempt_id`, `paid_amount`, `paid_method`, `latest_attempt`, `links.attempts` |
| `audit` | array | Latest 10 audit entries |
| `refund`, `ledger`, `return_charge`, `cancel_request` | object/array/null | Financial and cancellation records |
| `links` | object | History, audit, receipt, buyer/seller, payment, dispute and chat links; receipt can be null |
| `proof_images_max` | integer | Maximum allowed proof count returned by settings |

Money fields have **different shapes**: `snapshot.*` uses structured money objects; some row fields and `return_charge_outstanding` use decimal-formatted money values. Consume the server format rather than assuming a single money scalar.

### GET `/admin/orders/{ref}/history` and `/audit`

Both require `orders.view`; query `per_page` integer `1..100`.

| Endpoint | Default size | Order | Response |
|---|---:|---|---|
| `/history` | 50 | Oldest status history first (`id ASC`) | `{data: HistoryLine[], meta: {current_page,last_page,per_page,total}}` |
| `/audit` | 25 | Latest audit first (`id DESC`) | `{data: AuditChange[], meta: {current_page,last_page,per_page,total}}` |

History line schema: `id: integer`, `from: string|null`, `to: string`, `to_label: locale-map`, `reason: string|null`, `reason_label: locale-map|null`, `actor`, `actor_user: {id,name}|null`, `at: ISO-8601 string`. Audit changes are generated by `AdminOrderPresenter::change`; do not assume they have the same shape as history entries.

### POST `/admin/orders/{ref}/release-hold`

Permission `orders.holds.release`. Body: `{ "reason": "Operational review completed" }`. Reason is **required string, 3..400 characters**. The controller returns an `ApiResponse::ok` data object with `changed: boolean` and `order: AdminOrderDetail`, including updated payment summary. Treat `changed=false` as a successful no-op when permitted; refresh the detail from the response.

### POST `/admin/orders/{ref}/recheck-payment`

Permission `orders.payments.recheck`. No validated JSON body in the controller. Response data includes `payment_state`, `outcome`, `order` (full detail and payment summary). Recheck is an administrative action; do not invoke automatically on every dashboard render.

### Fulfilment and financial action contracts

All below are `POST`, `auth:sanctum`, and return `ApiResponse::ok` with `{changed: boolean, order: AdminOrderDetail}` after a successful state transition, except the two administrative payment/hold actions described above. The `order` includes refreshed fulfilment details. The route enforces the permission shown in the first table.

| Action suffix under `/admin/orders/{ref}` | Required body | Source behavior |
|---|---|---|
| `/picked-up` | none | Courier pickup; may move `preparing` to `in_delivery` |
| `/shipped` | none | Mark shipped; may move to `in_delivery` |
| `/courier-arrived` | `proofs: string[]` required | 1..configured max distinct uploaded media references; each `^med_[a-f0-9]{32}$` |
| `/delivery-failed` | `reason: string` | Required, 3..400 chars; buyer-related failed delivery, enters return flow |
| `/return-verified` | `note?: string|null` | Optional, max 400 chars; verifies return before refund/stock settlement |
| `/handed-over` | `note?: string|null` | Optional, max 400 chars; admin records direct hand-over |
| `/complete` | `note?: string|null` | Optional, max 400 chars; completes eligible arrived/awaiting-confirmation order |
| `/cancel` | `reason: string` | Required, 3..400 chars; after-shipping cancellation waits for return verification |
| `/return-charge/settle` | `note?: string|null` | Optional, max 400 chars; charge settled from seller available balance; insufficient balance can fail |
| `/return-charge/waive` | `reason: string` | Required, 3..400 chars; platform waives outstanding return charge |

`proofs` are uploaded beforehand through `POST /api/v1/media`; the max is `min(OrdersPolicy::proofImagesMax(), DeliveryProofs::SLOT_MAX)` (do not hardcode). **Illustrative request:**

```json
{"proofs":["med_0123456789abcdef0123456789abcdef"]}
```

**Illustrative successful response shape:**

```json
{"data":{"changed":true,"order":{"ref":"OUT-0001","fulfilment_actions":{"mark_shipped":false}}}}
```

The example intentionally omits other required detail fields and is **not** a complete response fixture. Source verifies the controller's inner data; confirm the global `ApiResponse` envelope and HTTP error status in integration tests.

**Dashboard implementation:** render buttons from `fulfilment_actions` and `actions` supplied by GET detail, but still handle server rejection when state changes concurrently. Do not settle refunds on an `awaiting_return` order until the verified return action succeeds. Audit and status-history are distinct tabs. Never let a role infer permission from button visibility alone.

**Navigation:** delivery board, cancellation decisions, and order settings/history are expanded in the following sections. Some nested presenter objects are described structurally rather than exhaustively field-by-field; do not treat illustrative JSON fragments as complete fixtures.

---

## Delivery board — source-reviewed contract

`GET /api/v1/admin/orders/delivery-board` — `auth:sanctum`, `orders.view`. The controller limits the board to `paid`, `preparing`, `in_delivery`, `arrived`, `awaiting_confirmation`, `cancel_requested`, `awaiting_return`, and `disputed` orders. Unlike the generic orders list, it is a fulfilment-oriented queue.

| Query parameter | Type | Rule / meaning |
|---|---|---|
| `page` | integer | Laravel paginator page |
| `per_page` | integer | Optional, 1–100, default 25 |
| `sort` | string | `paid_at`, `picked_up_at`, `arrived_at`, `auto_complete_at`, `status`, `id`; prefix `-` for descending. Default `paid_at` ascending |
| `filter[status]` | comma-separated string | Allowed board statuses only |
| `filter[delivery_method]` | string/list | Delivery method filter |
| `filter[city_id]`, `filter[seller_id]` | integer/list | One or more IDs |
| `filter[placed_from]`, `filter[placed_to]` | date | Valid date; inclusive day boundary |
| `filter[search]` | string | Order reference, matching buyer/seller, or exact shipment reference |
| `filter[overdue]` | boolean-like | Overdue courier delivery |
| `filter[failed]` | boolean-like | Recorded delivery failure |
| `filter[delivery_issue]` | boolean-like | Carrier issue reported while still in delivery |
| `filter[awaiting_confirmation]` | boolean-like | Arrived / awaiting buyer confirmation |
| `filter[auto_complete_due]` | boolean-like | Completion deadline passed |
| `filter[picked_up]` | boolean-like | Courier has collected items |
| `filter[picked_up_from]`, `filter[picked_up_to]` | date | Pickup date interval |
| `filter[arrived_from]`, `filter[arrived_to]` | date | Arrival date interval |

**Response:** a direct JSON object (not `ApiResponse::ok`) with `data: array`, `links: {first,last,prev,next}`, and `meta: {current_page,from,last_page,per_page,to,total,statuses,overdue_hours,sorts}`. Each `data[]` starts with `AdminOrderPresenter::row(...)` and adds:

| Field | Type | Description |
|---|---|---|
| `pickup` | object/null | Stored seller pickup address snapshot |
| `address` | object/null | Stored buyer delivery address snapshot |
| `delivery_fee` | object | `{amount: decimal string, currency: string}` |
| `shipment` | object | `{driver: string|null, reference: string|null}` |
| `proofs` | integer | Count of proof images (not image objects) |
| `delivery_issue` | object/null | `{reported_at: ISO8601 string, note: string|null}` |
| `items` | array | `{product_id: integer, name: string}` per item |
| `auto_complete` | object/null | Countdown/display data from `FulfilmentViews::autoComplete` |
| `next_actions` | string[] | **Only** currently permitted and state-eligible action keys |

Illustrative **partial** list item (other fields from `AdminOrderPresenter::row` omitted):

```json
{
  "data": [{
    "ref": "OUT-0001",
    "shipment": {"driver": null, "reference": null},
    "proofs": 0,
    "delivery_fee": {"amount": "20.00", "currency": "SAR"},
    "items": [{"product_id": 12, "name": "Example product"}],
    "next_actions": ["mark_picked_up"]
  }],
  "links": {"first": "...", "last": "...", "prev": null, "next": null},
  "meta": {"current_page": 1, "per_page": 25, "total": 1}
}
```

The example is deliberately incomplete and uses placeholder values; do **not** treat it as a full response fixture. Render actions from `next_actions`, then refresh after mutation. The same eligibility rules are returned as booleans under `fulfilment_actions` in order detail.

## Seller cancellation queue and decisions — source-reviewed contract

All routes below require `auth:sanctum`; read endpoints require `orders.view`; decisions require `orders.cancel_requests.decide`. `{requestRef}` matches `[A-Za-z]{2}-\\d{1,12}` at routing level.

| Method | Path | Permission | Purpose |
|---|---|---|---|
| GET | `/api/v1/admin/orders/cancel-requests` | `orders.view` | Paginated decision queue |
| GET | `/api/v1/admin/orders/cancel-requests/{requestRef}` | `orders.view` | Request and associated order details |
| POST | `/api/v1/admin/orders/cancel-requests/{requestRef}/approve` | `orders.cancel_requests.decide` | Approve seller cancellation |
| POST | `/api/v1/admin/orders/cancel-requests/{requestRef}/reject` | `orders.cancel_requests.decide` | Reject seller cancellation |

### GET cancellation queue

| Query | Type | Rule |
|---|---|---|
| `page` | integer | Laravel paginator page |
| `per_page` | integer | Optional 1–100, default 25 |
| `sort` | string | `requested_at`, `decided_at`, `id`, optionally prefixed `-`; default `-requested_at` |
| `filter[status]` | string/list | `pending`, `approved`, `rejected`, `withdrawn` |
| `filter[reason]` | string/list | `item_unavailable`, `item_damaged`, `cannot_deliver_in_time`, `other` |
| `filter[seller_id]`, `filter[buyer_id]`, `filter[decided_by]` | integer/list | ID filters |
| `filter[requested_from]`, `filter[requested_to]` | date | Request date range |
| `filter[delivery_method]`, `filter[city_id]` | string/list | Method / city filters |
| `filter[amount_min]`, `filter[amount_max]` | decimal string | Up to 9 integer digits and 2 decimal places |
| `filter[search]` | string | Search callback; see `OrderListFilters` for matching behavior |

**Response:** direct JSON `{data, links, meta}`. `meta` contains paginator keys plus `statuses`, `reasons`, `sorts` (localized label arrays), and `pending` (integer: total pending requests). `data[]` is `AdminOrderPresenter::cancelRequestRow`:

| Field | Type | Notes |
|---|---|---|
| `ref`, `order_ref` | string | Cancellation reference and order reference |
| `status`, `reason` | string | Machine-readable enums |
| `status_label`, `reason_label` | object | Enabled-locale labels, e.g. `ar`/`en` when enabled |
| `note`, `decision_note` | string/null | Seller and admin notes |
| `seller_id`, `buyer_id` | integer | Parties |
| `order_status_at_request` | string | Snapshot of order state |
| `requested_at`, `decided_at` | ISO8601 string/null | Timeline |
| `decided_by` | integer/null | Admin ID |
| `order` | object/null | Associated order summary when eager-loaded |
| `links.order` | string | Admin order details endpoint |

### GET cancellation request detail

Returns `ApiResponse::ok(...)` containing the cancellation row fields above plus `seller` and `buyer` people summaries (or null), `order_detail` (the full `AdminOrderPresenter::detail` object), `audit` (recent order audit array), and `can_decide: boolean`. `can_decide` is true only when request status is `pending` **and** the current admin has `orders.cancel_requests.decide`.

### POST approve / reject

| Body field | Type | Validation |
|---|---|---|
| `note` | string/null | Optional; maximum 500 characters |

Both actions return `ApiResponse::ok({changed: boolean, request: CancelRequestRow})`. A repeated decision can return `changed: false`; never assume each `200` implies a new state change. Approving cancels the pre-shipment order and refunds the buyer; rejecting restores the prior order flow. The exact domain error response envelope remains unverified in live HTTP tests.

**Illustrative partial response:**

```json
{
  "data": {
    "changed": true,
    "request": {
      "ref": "CR-12",
      "order_ref": "OUT-0001",
      "status": "approved",
      "reason": "item_unavailable"
    }
  }
}
```

The sample omits required fields of the actual `request` object and assumes a generic API envelope for illustration; verify `ApiResponse` serialization before using it as a test fixture.

### Implementation notes

- Keep `GET` queue and `GET` detail distinct; detail includes related order and audit information.
- Use `meta.pending` for the queue badge, not just the current page's pending rows.
- Disable decision buttons when `can_decide` is false; still handle concurrent server-side state changes.
- Reuse `OrderListFilters` for exports to match the filtered dashboard list exactly.
- Order settings/history and remaining nested presenter schemas are pending a separate source review.

**Sources:** `modules/Orders/Interfaces/Http/Controllers/Admin/FulfilmentAdminController.php`, `modules/Orders/Interfaces/Http/Requests/{DeliveryBoardRequest,CancelRequestsRequest,DecisionNoteRequest}.php`, `modules/Orders/Infrastructure/ReadModel/OrderListFilters.php`, `modules/Orders/Interfaces/Http/Presenters/AdminOrderPresenter.php` (`main`).


## Order settings — source-reviewed contracts (2026-11-22)

Source: [`OrderSettingsController.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Interfaces/Http/Controllers/Admin/OrderSettingsController.php), [`OrderSettingsRequest.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Interfaces/Http/Requests/OrderSettingsRequest.php), [`PageRequest.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Interfaces/Http/Requests/PageRequest.php), and `modules/Orders/Routes/api.php` on `main`. Static code review; runtime error envelopes are not verified.

All three routes require `auth:sanctum`, `can:settings.manage`, and `LocalizeOrderErrors`. Paths are relative to `/api/v1`.

| Method | Path | Purpose | Successful response |
|---|---|---|---|
| GET | `/admin/orders/settings` | Read checkout, order, cancellation, refund, receipt settings | `ApiResponse::ok(settings)` |
| PATCH | `/admin/orders/settings` | Partial settings update with audit | `ApiResponse::ok(settings + changed + changes)` |
| GET | `/admin/orders/settings/history` | Read descending audit events | Raw paginated JSON with `data`, `links`, `meta` |

### GET `/admin/orders/settings` — response fields

| JSON path | Type | Description |
|---|---|---|
| `checkout.hold_minutes` | integer | Checkout reservation duration |
| `orders.auto_complete_hours` | integer | Automatic completion delay |
| `orders.proof_images_max` | integer | Maximum proof photos |
| `orders.direct_auto_complete_hours` | integer | `0` means never auto-complete direct handover |
| `orders.delivery_overdue_hours` | integer | Threshold for overdue delivery |
| `orders.alert_recipients` | array of integer | Alert recipient user IDs |
| `cancel.buyer_before_shipping` | boolean | Buyer cancellation gate |
| `cancel.seller_request_before_shipping` | boolean | Seller cancellation-request gate |
| `refund.delivery_fee_if_service_done` | boolean | Delivery-fee policy |
| `refund.service_fee` | boolean | Service-fee refund policy |
| `refund.return_shipping_payer` | string | Value from `options.return_shipping_payer` |
| `refund.buyer_failure.keep_commission` | boolean | Commission retention on buyer failure |
| `refund.buyer_failure.keep_delivery_fee` | boolean | Delivery-fee retention on buyer failure |
| `receipt.platform_name` | localized text object | Platform name in receipt PDF |
| `receipt.logo_url` | string or null | Receipt logo |
| `receipt.support_phone` | string or null | Contact phone |
| `receipt.support_email` | string or null | Contact email |
| `receipt.website` | string or null | Contact website |
| `receipt.footer_note` | localized text object or null | Receipt footer |
| `options.return_shipping_payer` | string[] | Allowed values for refund payer |
| `limits` | object | Backend-provided min/max values for numeric settings |
| `units` | object | Display units for durations and photo count |

The localized text structure is validated by `LocalizedTextRule`; do not assume that an arbitrary `{ar,en}` object is sufficient without reviewing that rule and enabled locales. Prefer rendering options/limits returned by GET rather than hardcoding them.

### PATCH `/admin/orders/settings` — request and validation

`Content-Type: application/json`. All groups and leaf fields are optional; send only changed fields.

| JSON path | Type | Validation |
|---|---|---|
| `checkout.hold_minutes` | integer | 5–120 |
| `orders.auto_complete_hours` | integer | 1–720 |
| `orders.proof_images_max` | integer | 1–`DeliveryProofs::SLOT_MAX` (read from `limits`) |
| `orders.direct_auto_complete_hours` | integer | 0–720 |
| `orders.delivery_overdue_hours` | integer | 1–720 |
| `orders.alert_recipients` | integer[] | At most 50 distinct IDs, each >= 1 |
| `cancel.buyer_before_shipping` | boolean | Optional |
| `cancel.seller_request_before_shipping` | boolean | Optional |
| `refund.delivery_fee_if_service_done` | boolean | Optional |
| `refund.service_fee` | boolean | Optional |
| `refund.return_shipping_payer` | string | Must match one of `options.return_shipping_payer` |
| `refund.buyer_failure.keep_commission` | boolean | Optional |
| `refund.buyer_failure.keep_delivery_fee` | boolean | Optional |
| `receipt.platform_name` | localized text | Required when present; localized maximum 60 |
| `receipt.logo_url` | URL or null | HTTP(S), max 500 characters |
| `receipt.support_phone` | string or null | Max 30; pattern `^\+?[0-9 ]{5,20}$` |
| `receipt.support_email` | email or null | Max 150 |
| `receipt.website` | URL or null | HTTP(S), max 150 |
| `receipt.footer_note` | localized text or null | Localized maximum 200 |
| `reason` | string or null | Max 300; optional audit reason |

**Illustrative PATCH request** (valid field types; not a captured response):

```http
PATCH /api/v1/admin/orders/settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "checkout": {"hold_minutes": 30},
  "orders": {"delivery_overdue_hours": 48},
  "cancel": {"buyer_before_shipping": true},
  "reason": "Operations policy review"
}
```

Successful PATCH returns the **same settings structure as GET** plus:

| JSON path | Type | Meaning |
|---|---|---|
| `changed` | boolean | `false` when submitted values produce no effective changes |
| `changes` | array of objects | Each `{setting: string, old: mixed, new: mixed}` |

Example **data payload only** (not a full envelope):

```json
{
  "changed": true,
  "changes": [
    {"setting": "checkout.hold_minutes", "old": 20, "new": 30}
  ]
}
```

The exact `setting` string in an audit change is generated by `OrderSettingRow::auditChanges`; the sample above is illustrative, not an asserted observed value. For `receipt.logo_url`, `support_phone`, `support_email`, `website`, blank strings or `null` clear the field. `receipt.footer_note: null` clears it. Other non-receipt settings use `null` as **unchanged** (not reset). Existing order hold deadlines, auto-complete deadlines and refund terms are snapshots: settings changes apply to later events/orders rather than retroactively rewriting fixed terms.

### GET `/admin/orders/settings/history` — pagination and response

| Query parameter | Type | Validation/default |
|---|---|---|
| `page` | integer | Standard Laravel pagination; not explicitly validated by `PageRequest` |
| `per_page` | integer | 1–100; default 25 |

This endpoint returns a **raw paginated JSON object**, not the `ApiResponse::ok` shape:

```json
{
  "data": [
    {
      "id": 123,
      "event": "updated",
      "old_values": {},
      "new_values": {},
      "actor_id": 42,
      "at": "2026-11-22T10:00:00+00:00"
    }
  ],
  "links": {"first": "...", "last": "...", "prev": null, "next": null},
  "meta": {"current_page": 1, "from": 1, "last_page": 1, "per_page": 25, "to": 1, "total": 1}
}
```

The sample values above are illustrative. History is ordered newest first by audit ID, scoped to `OrderSettingRow::MORPH`. `old_values`/`new_values` are audit payloads; do not assume every event contains the same keys. `actor_id` and `at` can be `null`.

### Dashboard integration checklist

- Read `options.return_shipping_payer`, `limits`, and `units` before rendering the settings form.
- PATCH only edited fields, then use the returned settings snapshot and `changed` flag.
- Treat `receipt` clearing semantics separately from other settings.
- Render history as a separate paginated list; do not reuse the settings `ApiResponse` parser.
- Handle validation and authorization failures from the server; their exact serialized error shapes remain to be runtime-verified.

## Admin Orders error handling — source-reviewed

Admin Orders uses the same `LocalizeOrderErrors` middleware and `OrderStateConflict` domain errors as Flutter Orders. HTTP **409** indicates an order-state/business conflict, not a validation failure. The middleware localizes `error.message` and attaches `error.details.order_ref` for `OrderStateConflict`, plus `status` when provided by the exception. `order_not_found` is **404**. Admin actions must always be gated by server permissions and fresh `actions`/`fulfilment_actions` values.

| Error code | HTTP | Dashboard scenario / reaction |
|---|---:|---|
| `order_hold_not_releasable` | 409 | Release-hold no longer valid; refresh order |
| `order_not_shippable`, `order_not_in_delivery` | 409 | Delivery transition no longer valid; refresh board/detail |
| `order_not_direct`, `order_not_courier`, `order_not_handable` | 409 | Wrong method/state for hand-over; refresh allowed actions |
| `order_not_confirmable`, `order_disputed` | 409 | Completion cannot proceed; refresh and inspect dispute |
| `order_not_cancellable` | 409 | Admin cancellation no longer allowed; refresh |
| `order_not_awaiting_return` | 409 | Return verification unavailable; refresh |
| `cancel_request_not_pending`, `cancel_request_already_decided` | 409 | Approval/rejection race or prior decision; reload request |
| `return_charge_not_outstanding` | 409 | Charge already resolved/not present; reload charge state |
| `receipt_not_available`, `receipt_payment_rejected` | 409 | Receipt cannot be fetched; refresh receipt link |
| `order_not_found` | 404 | Unknown order or unavailable record |

**Do not assume** every error has `details` or that HTTP 422 validation failures share the Orders business-error structure. Source: [`LocalizeOrderErrors.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Interfaces/Http/Middleware/LocalizeOrderErrors.php), [`OrderStateConflict.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Orders/Domain/Exception/OrderStateConflict.php). Live status/error-envelope tests still pending.


---

## Endpoint coverage reconciliation — GitLab `main` (2026-11-22)

Reviewed `modules/Orders/Routes/api.php` directly against this document. The Dashboard group contains **25 HTTP route definitions**, all listed in the inventory above; `Route::match(['get','post'], 'checkout/quote', ...)` belongs to Flutter, not Dashboard. The complete Orders module has 40 route definitions (one `match` declaration exposes two HTTP methods).

| Functional area | Dashboard routes | Documentation location | Status |
|---|---:|---|---|
| Settings and settings audit | 3 | Order settings | Source reviewed |
| Orders list, detail, history, audit, receipt | 5 | Order list/detail/audit; receipt link | Source reviewed; receipt media/headers require runtime test |
| Delivery board and cancellation queue/detail | 3 | Delivery board; cancellation queue | Source reviewed |
| Hold and payment recheck | 2 | Admin actions | Source reviewed |
| Delivery/fulfilment transitions | 6 | Fulfilment actions | Source reviewed |
| Complete/cancel and return charge settlement/waiver | 4 | Fulfilment and financial actions | Source reviewed |
| Seller cancellation approve/reject | 2 | Cancellation decisions | Source reviewed |
| **Total** | **25** | | **See note below** |

**Counting note:** the inventory has 25 Dashboard routes (3 + 5 + 3 + 2 + 6 + 4 + 2 = 25). The source has 25 `Route::get/post/patch` calls under `admin/orders`; this table is the authoritative Dashboard count. The module-wide count of 40 includes app endpoints.

**Release gate:** code review does not establish actual status codes for every domain failure, permissions for a real operator role, binary receipt rendering, or concurrency/idempotency behavior in a running environment. Verify those on Staging before final API handoff.
