> **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.

# Locations — Outlet API handoff (dashboard)

> **Verification boundary:** The detailed contract below was derived from repository source, not from live HTTP captures. Fields explicitly marked unverified remain open. The earlier route inventory is retained below for cross-checking; where it says “not verified”, the more recent source-reviewed contract takes precedence.

## Controller-reviewed contracts


**Source:** GitLab `alalmiyalhura/outlet`, `main`, `modules/Locations/Routes/api.php`, `CityController`, `AdminCityController`, `CityRequest`, `CityPresenter`, `CityHistory`, `City` domain. Base URL `/api/v1`. Examples are **illustrative source-derived shapes, not live captures**. Success payloads use `{"data": ...}` unless pagination is described. The backend may emit additional localized error details. `Accept-Language: ar` determines localized app names and error messages.

## 1. GET `/api/v1/cities` — Flutter city picker

Public; no bearer token. Throttle 120/min. **Request:** no body or query parameters. **Success 200:** `data` is an array of **active** cities, sorted by display order. Each row: `id` integer required, `slug` string required, `name` string required (translated into request locale, Arabic fallback).

```http
GET /api/v1/cities
Accept-Language: ar
```
```json
{"data":[{"id":1,"slug":"riyadh","name":"الرياض"},{"id":2,"slug":"jeddah","name":"جدة"}]}
```

**Errors:** rate limit 429 possible. No input validation. Use on registration, address and city selectors; deactivated cities are excluded from new choices.

## 2. GET `/api/v1/admin/cities` — dashboard city list

Bearer **dashboard** session; permission `cities.view`. **Request:** no body; optional query:

| Parameter | Type | Required | Validation / meaning |
|---|---|---|---|
| `filter[active]` or `active` | string/bool | No | `1`, `0`, `true`, `false` (case-insensitive strings) |
| `filter[q]`, `filter[search]` or `q` | string | No | max 100; search slug and translated names |
| `filter[created_from]`, `filter[created_to]` | date | No | valid date; `to >= from`; also plain names accepted |
| `filter[updated_from]`, `filter[updated_to]` | date | No | valid date; `to >= from`; also plain names accepted |
| `sort` | enum string | No | `sort_order`, `name`, `slug`, `created_at`, `updated_at`, or each prefixed `-`; default `sort_order` |
| `per_page` | integer | No | 1–100; default 50 |
| `page` | integer | No | >= 1; default 1 |

Plain parameters override nested `filter` equivalents. **Response fields:** `data[]` CityAdmin; `links.{first,last,prev,next}` URL or null; `meta.{current_page,last_page,per_page,total,from,to}` integers (from/to nullable). **CityAdmin:** `id` integer; `slug` string; `name` object of locale→string; `is_active` boolean; `sort_order` integer; `created_at`, `updated_at` ISO 8601 strings or null.

```http
GET /api/v1/admin/cities?filter[active]=true&sort=name&per_page=20&page=1
Authorization: Bearer <dashboard-token>
```
```json
{"data":[{"id":1,"slug":"riyadh","name":{"ar":"الرياض","en":"Riyadh"},"is_active":true,"sort_order":0,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:00:00+00:00"}],"links":{"first":"https://example.test/api/v1/admin/cities?page=1","last":"https://example.test/api/v1/admin/cities?page=1","prev":null,"next":null},"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1,"from":1,"to":1}}
```

**Errors:** 401 unauthenticated; 403 permission denied; 422 invalid filter/sort/page.

## 3. GET `/api/v1/admin/cities/{id}` — city detail

Dashboard bearer; `cities.view`. **Path:** `id` required positive-looking numeric route parameter (`whereNumber`); no body/query. **Success 200:** `data` = CityAdmin (all fields and types defined above).

```http
GET /api/v1/admin/cities/1
Authorization: Bearer <dashboard-token>
```
```json
{"data":{"id":1,"slug":"riyadh","name":{"ar":"الرياض","en":"Riyadh"},"is_active":true,"sort_order":0,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:00:00+00:00"}}
```

**Errors:** 401, 403, 404 city not found.

## 4. GET `/api/v1/admin/cities/{id}/history` — audit history

Dashboard bearer; `cities.view`. **Path:** numeric `id` required. **Query:** `per_page` optional integer 1–100 (default 25), `page` optional integer >=1. **Success 200:** top-level `data[]` and `meta` (not nested under `data`). Audit row: `id` integer; `event` string; `actor` nullable object `{id: integer, name: string|null}`; `old_values` object of changed columns; `new_values` object; `created_at` ISO date string|null. For changed `name`, audit values are locale maps when decodable; `is_active` boolean and `sort_order` integer when present. `meta`: `current_page`, `last_page`, `per_page`, `total` integers.

```http
GET /api/v1/admin/cities/1/history?per_page=25&page=1
Authorization: Bearer <dashboard-token>
```
```json
{"data":[{"id":9,"event":"updated","actor":{"id":3,"name":"Admin"},"old_values":{"is_active":true},"new_values":{"is_active":false},"created_at":"2026-11-22T10:00:00+00:00"}],"meta":{"current_page":1,"last_page":1,"per_page":25,"total":1}}
```

**Errors:** 401, 403, 404 missing city, 422 pagination validation.

## 5. POST `/api/v1/admin/cities` — create city

Dashboard bearer; `cities.manage`. **Request fields:**

| Field | Type | Required | Validation |
|---|---|---|---|
| `name` | object locale→string | Yes | default platform language required, others optional if enabled; unknown/disabled keys rejected; each translation max 100 characters, not blank |
| `slug` | string | Yes | max 60; regex `^[a-z0-9]+(?:-[a-z0-9]+)*$` |
| `sort_order` | integer | No | 0–1,000,000 |
| `is_active` | boolean | No | default true |

```http
POST /api/v1/admin/cities
Authorization: Bearer <dashboard-token>
Content-Type: application/json
```
```json
{"name":{"ar":"الرياض","en":"Riyadh"},"slug":"riyadh","sort_order":0,"is_active":true}
```
**Success 201:** `data` = CityAdmin:
```json
{"data":{"id":1,"slug":"riyadh","name":{"ar":"الرياض","en":"Riyadh"},"is_active":true,"sort_order":0,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:00:00+00:00"}}
```
**Errors:** 401, 403, 422 validation; domain constraints and duplicate slug can produce business errors (exact error codes require separate exception-handler audit).

## 6. PATCH `/api/v1/admin/cities/{id}` — edit city

Dashboard bearer; `cities.manage`. **Path:** numeric `id` required. **Request:** all optional, but if present validated: `name` localized object (same rules as create), `slug` string max60 and same regex, `sort_order` integer 0–1,000,000. **`is_active` prohibited**; use activate/deactivate routes. No other fields accepted as update operations.

```http
PATCH /api/v1/admin/cities/1
Authorization: Bearer <dashboard-token>
Content-Type: application/json
```
```json
{"name":{"ar":"الرياض","en":"Riyadh City"},"sort_order":10}
```
**Success 200:**
```json
{"data":{"id":1,"slug":"riyadh","name":{"ar":"الرياض","en":"Riyadh City"},"is_active":true,"sort_order":10,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:05:00+00:00"}}
```
**Response fields:** CityAdmin. **Errors:** 401, 403, 404 missing city, 422 validation; domain uniqueness may also reject a slug.

## 7. POST `/api/v1/admin/cities/{id}/activate` — activate city

Dashboard bearer; `cities.status`. **Path:** numeric `id`; **request body:** none. Idempotent if already active. **Success 200** returns CityAdmin with `is_active: true`.

```http
POST /api/v1/admin/cities/1/activate
Authorization: Bearer <dashboard-token>
```
```json
{"data":{"id":1,"slug":"riyadh","name":{"ar":"الرياض","en":"Riyadh"},"is_active":true,"sort_order":0,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:05:00+00:00"}}
```
**Errors:** 401, 403, 404. This enables selection in the public city picker.

## 8. POST `/api/v1/admin/cities/{id}/deactivate` — deactivate city

Dashboard bearer; `cities.status`. **Path:** numeric `id`; **request body:** none. Idempotent if already inactive. **Success 200** returns CityAdmin with `is_active: false`.

```http
POST /api/v1/admin/cities/1/deactivate
Authorization: Bearer <dashboard-token>
```
```json
{"data":{"id":1,"slug":"riyadh","name":{"ar":"الرياض","en":"Riyadh"},"is_active":false,"sort_order":0,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:05:00+00:00"}}
```
**Errors:** 401, 403, 404. Existing references to the city remain valid; there is deliberately no DELETE route.

## 9. PUT `/api/v1/admin/cities/order` — reorder all cities

Dashboard bearer; `cities.manage`. **Request:** `ids` required array, at least one entry; each `ids.*` integer and distinct. The handler may enforce that IDs form a valid complete city set (check domain implementation before assuming partial lists are allowed). **Success 200:** `data[]` = entire **unpaginated** city list as CityAdmin rows in new order.

```http
PUT /api/v1/admin/cities/order
Authorization: Bearer <dashboard-token>
Content-Type: application/json
```
```json
{"ids":[2,1,3]}
```
```json
{"data":[{"id":2,"slug":"jeddah","name":{"ar":"جدة","en":"Jeddah"},"is_active":true,"sort_order":0,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:05:00+00:00"},{"id":1,"slug":"riyadh","name":{"ar":"الرياض","en":"Riyadh"},"is_active":true,"sort_order":1,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:05:00+00:00"},{"id":3,"slug":"dammam","name":{"ar":"الدمام","en":"Dammam"},"is_active":true,"sort_order":2,"created_at":"2026-11-22T10:00:00+00:00","updated_at":"2026-11-22T10:05:00+00:00"}]}
```
**Errors:** 401, 403, 422 malformed/duplicate IDs; additional domain errors possible for unknown or incomplete ID sets.

---

## Screen coverage notes

- **Flutter:** city selection for registration/profile/address/checkout can use public `GET /cities`; actual Flutter source integration **not verified**.
- **Dashboard:** city list, detail, create, edit, status, reorder and history map to the 8 admin routes above; actual dashboard source integration **not verified**.
- **Route count:** 9 Locations routes inspected; 9 fully described here. Other modules are not certified complete by this file.
- **Verification scope:** source review only. No staging/live calls or authenticated end-to-end tests performed.


---

## Earlier route inventory (historical; superseded by contracts above)

# Locations API — Dashboard

Source: [`modules/Locations/Routes/api.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Locations/Routes/api.php).

> **Verification:** HTTP methods, paths, route-level authentication and route comments are confirmed from source. Exact request and response schemas are **not verified** unless explicitly described. Do not treat illustrative placeholders as real API payloads.

Endpoints in this file: **8**.

## `GET /api/admin/cities`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/admin/cities/{id}`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/admin/cities/{id}/history`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/admin/cities`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `PUT /api/admin/cities/order`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `PATCH /api/admin/cities/{id}`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/admin/cities/{id}/activate`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/admin/cities/{id}/deactivate`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** cities.view / manage / status (by method)
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.
