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

# Delivery — Flutter source-reviewed API contracts

**Base URL:** `/api/v1`. **Accept:** `application/json`. Examples are illustrative values with source-verified field names, not captured runtime traffic. Validation errors are normally 422; do not assume a particular global error envelope without runtime verification.

**Sources:** [api.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Delivery/Routes/api.php), [DeliveryController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Delivery/Interfaces/Http/Controllers/DeliveryController.php), [DeliveryPresenter.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Delivery/Interfaces/Http/Presenters/DeliveryPresenter.php). Reviewed against `main` on 2026-11-22. All three endpoints are **public** (no Sanctum auth), under `throttle:120,1` and localized business-error middleware.

## `GET /api/v1/delivery/options`

**Screen:** Checkout delivery method selector. **Query:**

| Name | Type | Required | Validation |
|---|---|---|---|
| `city_id` | integer | Yes | >=1, must exist in city directory |
| `seller_city_id` | integer | Yes | >=1, must exist in city directory |

```http
GET /api/v1/delivery/options?city_id=1&seller_city_id=2 HTTP/1.1
Accept: application/json
```

**200 response (illustrative):**
```json
{"data":{"city_id":1,"seller_city_id":2,"default_method":"direct","currency":"SAR","courier_notice":null,"methods":[{"method":"direct","label":"Direct handover","short_label":"Direct","description":"Arrange handover","available":true,"selected":true,"fee":"0.00","currency":"SAR","is_free":true,"fee_text":"Free","estimated_days":null,"unavailable_reason":null,"unavailable_message":null}]}}
```

| JSON path | Type | Notes |
|---|---|---|
| `data.city_id`, `data.seller_city_id` | integer | Echo validated cities |
| `data.default_method` | string or null | First available method; null if none available |
| `data.currency` | string | Configured fee currency |
| `data.courier_notice` | string or null | Localized reason if courier is unavailable |
| `data.methods` | array<object> | One entry per offered delivery method |
| `methods[].method` | string | Backend delivery-method enum (e.g. `courier`, `direct`) |
| `methods[].label`, `.short_label`, `.description` | string | Ready-to-display localized text |
| `methods[].available`, `.selected`, `.is_free` | boolean | Server-derived; do not recompute |
| `methods[].fee` | decimal string or null | Null when unavailable; money is a decimal **string** |
| `methods[].currency` | string | ISO-style currency code |
| `methods[].fee_text` | string or null | Free/unavailable label; may be null for priced method |
| `methods[].estimated_days` | string or null | Localized courier estimate |
| `methods[].unavailable_reason`, `.unavailable_message` | string or null | Machine reason and display message |

**Errors:** `422` invalid/unknown city; `429` throttle. **Business rule:** select `default_method`, not the first item unconditionally.

## `GET /api/v1/delivery/coverage`

**Screen:** Address form, saved-address availability and seller pickup checks.

| Query parameter | Type | Required | Validation |
|---|---|---|---|
| `city_ids[]` | array<integer> | No | Max 50; each ID >=1 and must exist in city directory |

```http
GET /api/v1/delivery/coverage?city_ids[]=1&city_ids[]=2 HTTP/1.1
Accept: application/json
```

**200 response (illustrative):**
```json
{"data":{"courier_enabled":true,"direct_enabled":true,"currency":"SAR","hint":"Fees vary by city","courier_notice":null,"cities":[{"city_id":1,"name":"Riyadh","is_active":true,"courier_available":true,"pickup_available":true,"fee":"25.00","currency":"SAR","estimated_days":"2–3 days","note":null,"checkout_note":null,"pickup_note":null,"seller_note":null}]}}
```

| JSON path | Type | Notes |
|---|---|---|
| `data.courier_enabled`, `.direct_enabled` | boolean | Global delivery settings |
| `data.currency` | string | Configured currency |
| `data.hint` | string | Localized display hint |
| `data.courier_notice` | string or null | Notice when global courier delivery is disabled |
| `data.cities` | array<object> | All active cities plus specifically requested inactive cities |
| `cities[].city_id` | integer | City identifier |
| `cities[].name` | string | Localized city name |
| `cities[].is_active`, `.courier_available`, `.pickup_available` | boolean | Server-calculated availability |
| `cities[].fee` | decimal string or null | Null when courier unavailable |
| `cities[].currency` | string | Currency |
| `cities[].estimated_days` | string or null | Localized estimate |
| `cities[].note`, `.checkout_note`, `.pickup_note`, `.seller_note` | string or null | Localized conditional UI copy |

**Errors:** `422` invalid/unknown city or >50 entries; `429` throttled. **Business rule:** An inactive city is returned only if explicitly requested; it must be shown as inactive/uncovered.

## `GET /api/v1/delivery/methods`

**Screen:** Delivery method labels on orders and incoming-order views. **Request:** no query/path/body.

```http
GET /api/v1/delivery/methods HTTP/1.1
Accept: application/json
```

**200 response (illustrative):**
```json
{"data":[{"method":"direct","label":"Direct handover","short_label":"Direct","description":"Arrange handover","place_note":"Agree on a location","enabled":true,"fee":"0.00","currency":"SAR"}]}
```

| Item field | Type | Notes |
|---|---|---|
| `method` | string | Delivery-method enum |
| `label`, `short_label`, `description` | string | Localized UI strings |
| `place_note` | string or null | Direct-handover note, null for courier |
| `enabled` | boolean | Configured global method availability |
| `fee` | decimal string or null | Direct fee; courier returns null here (get quote/options instead) |
| `currency` | string | Currency code |

**Errors:** `429` throttle. **Important:** Method list is not a delivery price quote; courier fees depend on city and checkout context.
