> **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 — Carts API (source-reviewed contract)

**Source:** `modules/Cart/Routes/api.php`, `CartAdminController.php`, `CartSettingsController.php`, request classes, `CartListFilters.php`, `CartViews.php`, `CartSettings.php` on `main`. Base `/api/v1`. All six endpoints require Bearer token. `settings.manage` for settings/history; `carts.view` for list/detail/history. **Dashboard cart access is read-only**; no admin cart mutation route.

## Common shapes
- `Money`: `{ "amount":"120.00", "currency":"SAR" }`, both strings.
- Paginated response (not wrapped under `data.data`): `data` array, `links` `{first,last,prev,next}` URL/null, `meta` `{current_page,from,last_page,per_page,to,total}` (numbers; `from`/`to` may be null).
- Success for single object: `{ "data": { ... } }`.
- Examples are illustrative, not captured from a running API.

### GET `/admin/carts/settings`
- **Permission:** `settings.manage`; no request body/query.
- **200 response:** `data.max_items` integer; `data.abandoned_after_hours` integer. Values are deployment-configured.
```json
{"data":{"max_items":30,"abandoned_after_hours":48}}
```

### PATCH `/admin/carts/settings`
- **Permission:** `settings.manage`.
| Body field | Type | Validation |
|---|---|---|
| `max_items` | integer | Optional, 1–100 |
| `abandoned_after_hours` | integer | Optional, 1–2160 |
| `reason` | string/null | Optional, max 300 chars; audit reason |
```json
{"max_items":30,"abandoned_after_hours":48,"reason":"Operational update"}
```
- **200 response:** `{ "data": { "max_items": 30, "abandoned_after_hours": 48 } }`; settings changes are audited old→new.

### GET `/admin/carts/settings/history`
- **Permission:** `settings.manage`; query `per_page` optional integer 1–100, default 25; `page` standard pagination query.
- **200:** paginated `data[]` entries: `id` integer, `event` string, `old_values` object, `new_values` object, `actor_id` integer/null, `at` ISO8601 string/null.
```json
{"data":[{"id":7,"event":"updated","old_values":{"max_items":20},"new_values":{"max_items":30},"actor_id":2,"at":"2026-11-22T10:00:00+00:00"}],"links":{"first":"/api/v1/admin/carts/settings/history?page=1","last":"/api/v1/admin/carts/settings/history?page=1","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":25,"to":1,"total":1}}
```

### GET `/admin/carts`
- **Permission:** `carts.view`; query `per_page` optional integer 1–100 (default 15), `page` integer pagination, `sort` one of `last_activity_at`, `created_at`, `items_count`, `value`, `id` (prefix `-` for descending; default `-value`).
- **Filters** via `filter[key]` (Spatie QueryBuilder; comma-separated lists where applicable):
| Key | Type / behavior |
|---|---|
| `state` | list of `active`, `abandoned`, `empty` |
| `abandoned`, `has_unavailable` | boolean-like |
| `seller_id`, `user_id`, `product_id` | integer ID or comma-separated IDs |
| `min_value`, `max_value` | decimal string with up to 9 integer and 2 fraction digits |
| `min_items`, `max_items`, `min_age_hours`, `max_age_hours` | nonnegative integers |
| `last_activity_from`, `last_activity_to`, `created_from`, `created_to` | dates |
| `search` | buyer/seller name or phone, or `#<cart id>` |

**Without `filter[state]`, empty carts are excluded.**
```http
GET /api/v1/admin/carts?per_page=15&filter[state]=abandoned&sort=-value
```
- **200 `data[]` CartAdminRow:** `id` integer, `state` string, `is_abandoned` boolean, `buyer` `{id:integer,name:string|null,phone_masked:string|null,status:string}`, `seller` same/null, `items_count`, `available_count`, `unavailable_count` integers, `value` Money, `age_hours` integer, `last_activity_at` ISO8601 string, `created_at`/`updated_at` ISO8601 string/null.
- **Extra meta:** `abandoned_after_hours` integer, `states` string[], `sorts` array of `{value:string,label:object(locale→string)}`.
```json
{"data":[{"id":9,"state":"abandoned","is_abandoned":true,"buyer":{"id":4,"name":"Buyer","phone_masked":"***123","status":"active"},"seller":null,"items_count":2,"available_count":1,"unavailable_count":1,"value":{"amount":"150.00","currency":"SAR"},"age_hours":72,"last_activity_at":"2026-11-19T10:00:00+00:00","created_at":"2026-11-18T10:00:00+00:00","updated_at":"2026-11-19T10:00:00+00:00"}],"links":{"first":"/api/v1/admin/carts?page=1","last":"/api/v1/admin/carts?page=1","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":15,"to":1,"total":1,"abandoned_after_hours":48,"states":["active","abandoned","empty"],"sorts":[{"value":"value","label":{"ar":"القيمة","en":"Value"}}]}}
```

### GET `/admin/carts/{id}`
- **Permission:** `carts.view`; `{id}` required numeric path integer. **200:** `{ "data": CartAdminRow + { items, live, recent_activity, links } }`.
- `items[]`: `product_id` integer, `name` string/null, `cover_image_url` string/null, `size` string/null, `condition` string/object/null (Catalog-sourced), `seller_id` integer, `price` Money, `added_price` Money, `price_changed` boolean, `old_price` Money/null, `availability` string, `available` boolean, `product_status` string/null, `locked_order_ref` string/null, `added_at` ISO8601 string/null, `links.product` string.
- `live`: `items_total` Money, `available_count` integer, `checkout_blockers` string[]. `recent_activity[]`: activity record shape below (latest 10). `links`: `history` string, `buyer` string, `seller` string/null.
```json
{"data":{"id":9,"state":"active","is_abandoned":false,"buyer":{"id":4,"name":"Buyer","phone_masked":null,"status":"active"},"seller":null,"items_count":0,"available_count":0,"unavailable_count":0,"value":{"amount":"0.00","currency":"SAR"},"age_hours":1,"last_activity_at":"2026-11-22T10:00:00+00:00","created_at":"2026-11-22T09:00:00+00:00","updated_at":"2026-11-22T10:00:00+00:00","items":[],"live":{"items_total":{"amount":"0.00","currency":"SAR"},"available_count":0,"checkout_blockers":["empty"]},"recent_activity":[],"links":{"history":"/api/v1/admin/carts/9/history","buyer":"/api/v1/admin/accounts/4","seller":null}}}
```

### GET `/admin/carts/{id}/history`
- **Permission:** `carts.view`; `{id}` numeric. Query `per_page` optional integer 1–100 (default 25), `page` pagination, `event` optional enum `item_added|item_removed|cleared|availability_changed`, `product_id` optional integer >=1.
- **200 paginated data[]:** `id` integer, `event` string, `product_id` integer/null, `details` object/null (event-specific), `user_id` integer/null, `at` ISO8601 string.
```json
{"data":[{"id":51,"event":"item_added","product_id":101,"details":{},"user_id":4,"at":"2026-11-22T10:00:00+00:00"}],"links":{"first":"/api/v1/admin/carts/9/history?page=1","last":"/api/v1/admin/carts/9/history?page=1","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":25,"to":1,"total":1}}
```

## Error handling / implementation
- 401 unauthenticated; 403 lacking `settings.manage` or `carts.view`; 404 unknown cart; 422 invalid filters/body. Exact localized error payload must be checked against `LocalizeCartErrors` and global exception handler.
- Use server-supplied `state`, `is_abandoned`, `value`, and `live.checkout_blockers`; do not recompute abandonment/price on the client. No admin write route for a cart exists.

**Source:** `modules/Cart/Interfaces/Http/Controllers/Admin/{CartAdminController,CartSettingsController}.php`, `modules/Cart/Infrastructure/ReadModel/CartListFilters.php`, `modules/Cart/Infrastructure/Settings/CartSettings.php`.


## Dashboard implementation checklist — source-verified details

### Route-to-screen matrix (6/6)

| HTTP | Complete route | Permission | Dashboard operation | Response |
|---|---|---|---|---|
| GET | `/api/v1/admin/carts` | `carts.view` | Search/filter/sort carts | `200`, paginated `data[]`, `links`, `meta` |
| GET | `/api/v1/admin/carts/{id}` | `carts.view` | Cart detail and live product availability | `200`, `data` object |
| GET | `/api/v1/admin/carts/{id}/history` | `carts.view` | Read append-only cart events | `200`, paginated `data[]`, `links`, `meta` |
| GET | `/api/v1/admin/carts/settings` | `settings.manage` | Read cart policy | `200`, `data` object |
| PATCH | `/api/v1/admin/carts/settings` | `settings.manage` | Edit cart policy | `200`, `data` object |
| GET | `/api/v1/admin/carts/settings/history` | `settings.manage` | Review audited setting changes | `200`, paginated `data[]`, `links`, `meta` |

### Request validation and filtering matrix

| Endpoint | Input | Required? | Code-level rule / behavior |
|---|---|---|---|
| List | `per_page` | No | Integer 1–100, default 15 |
| List | `page` | No | Standard paginator query |
| List | `sort` | No | `last_activity_at`, `created_at`, `items_count`, `value`, `id`; leading `-` reverses; default `-value` |
| List | `filter[state]` | No | `active`, `abandoned`, `empty`; comma-separated values supported; omitting it excludes empty carts |
| List | `filter[abandoned]`, `filter[has_unavailable]` | No | Boolean-like values; evaluated server-side |
| List | `filter[seller_id]`, `filter[user_id]`, `filter[product_id]` | No | One ID or comma-separated ID list |
| List | `filter[min_value]`, `filter[max_value]` | No | Decimal with 1–9 integer digits and up to 2 decimal places; amounts converted to minor units server-side |
| List | `filter[min_items]`, `filter[max_items]` | No | Integer >= 0 |
| List | `filter[min_age_hours]`, `filter[max_age_hours]` | No | Integer >= 0; age based on last activity |
| List | `filter[last_activity_from]`, `filter[last_activity_to]` | No | Date; inclusive day boundaries |
| List | `filter[created_from]`, `filter[created_to]` | No | Date; inclusive day boundaries |
| List | `filter[search]` | No | Buyer/seller name or phone, or numeric cart ID with optional `#` |
| Detail | `{id}` | Yes | Numeric route constraint; unknown ID returns 404 |
| Cart history | `{id}` | Yes | Numeric route constraint; unknown ID returns 404 |
| Cart history | `event` | No | `item_added`, `item_removed`, `cleared`, `availability_changed` |
| Cart history | `product_id` | No | Integer >= 1 |
| Cart history | `per_page` | No | Integer 1–100, default 25 |
| Settings update | `max_items` | No | Integer 1–100 |
| Settings update | `abandoned_after_hours` | No | Integer 1–2160 |
| Settings update | `reason` | No | Nullable string, max 300 characters; stored in audit metadata rather than settings |
| Settings history | `per_page` | No | Integer 1–100, default 25 |

**Important:** The list's `filter` keys without explicit validation rules are still restricted to the server's allowlist. Do not assume they accept arbitrary object structures. The cart list and `carts` export share the same `CartListFilters` implementation, so equivalent filters should yield matching selections.

### Response contract — cart detail nested fields

| JSON path | Type | Nullable? | Dashboard use |
|---|---|---|---|
| `data.id` | integer | No | Cart identifier |
| `data.state` | string | No | Server-derived active/abandoned/empty state |
| `data.is_abandoned` | boolean | No | Abandonment badge |
| `data.buyer` | object | No | `{id,name,phone_masked,status}`; deleted-user fallback possible |
| `data.seller` | object | Yes | Same person summary or null |
| `data.items_count` | integer | No | Total items |
| `data.available_count` | integer | No | Available items |
| `data.unavailable_count` | integer | No | Unavailable items |
| `data.value` | object | No | Money `{amount,currency}` |
| `data.age_hours` | integer | No | Age since last activity |
| `data.items[]` | array<object> | No | Current cart items, including live product state |
| `data.items[].price` | object | No | Current Money amount/currency |
| `data.items[].added_price` | object | No | Price at time of addition |
| `data.items[].price_changed` | boolean | No | Price-change indicator |
| `data.items[].old_price` | object | Yes | Catalog old price |
| `data.items[].availability` | string | No | Item availability state |
| `data.items[].locked_order_ref` | string | Yes | Associated order lock when present |
| `data.items[].links.product` | string | No | Product admin detail path |
| `data.live.items_total` | object | No | Live Money total |
| `data.live.available_count` | integer | No | Current available count |
| `data.live.checkout_blockers[]` | array<string> | No | Server-determined checkout blockers |
| `data.recent_activity[]` | array<object> | No | Latest 10 events; not a substitute for paginated history |
| `data.links.history` | string | No | Cart history route |
| `data.links.buyer` | string | No | Buyer admin route |
| `data.links.seller` | string | Yes | Seller admin route |

### UI and QA acceptance cases

1. Guest receives 401; signed-in user without `carts.view` receives 403 on cart list/detail/history. Settings endpoints independently require `settings.manage`.
2. Verify a list with `filter[state]=empty` includes empty carts, while the unfiltered list excludes them.
3. Verify `filter[search]=#123` and name/phone search, date boundaries, `sort=-value`, and pagination link retention.
4. Verify `PATCH` updates only submitted settings, and that the `reason` appears in the audit trail rather than the settings response.
5. Verify cart detail shows current item availability and prices; compare with the historical activity list, which is append-only.
6. Verify missing cart ID returns 404, invalid page size returns 422, and no admin cart mutation actions are exposed.

**Verification status:** All six route signatures and contracts above are checked against GitLab `main` source; these acceptance cases have **not** been run against Staging. Examples are illustrative, not captured HTTP traffic.

**Additional source references:** `modules/Cart/Routes/api.php`, `modules/Cart/Interfaces/Http/Requests/{CartsRequest,CartHistoryRequest,CartSettingsRequest}.php`, `modules/Cart/Infrastructure/ReadModel/CartListFilters.php`.
