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

# Catalog API — Flutter (source-reviewed contract)

Source: `alalmiyalhura/outlet` `main`, `modules/Catalog/Routes/api.php`. Base path `/api/v1`. All 24 app routes are enumerated below. Controller, request, presenter and domain rules have been reviewed at source level; live staging behavior is not certified.

## Route inventory (24 entries)

### Guest-accessible

| Method | Path | Purpose |
|---|---|---|
| GET | `/catalog/categories` | Active category tree |
| GET | `/catalog/categories/{id}` | Category detail and filter sheet |
| GET | `/catalog/categories/{id}/brand-options` | Category brand picker |
| GET | `/catalog/brands` | Active brands |
| GET | `/catalog/brands/{id}` | Brand detail |
| GET | `/catalog/lists/{key}` | Active lookup list |
| GET | `/catalog/size-scales` | Size scales |
| GET | `/catalog/products` | Browse products |
| GET | `/catalog/products/{id}` | Product detail |
| GET | `/catalog/featured` | Featured products |
| GET | `/catalog/new-arrivals` | New arrivals |
| GET | `/catalog/search/popular` | Popular searches |
| GET | `/home/banners` | Home banners |
| GET | `/home/sections` | Home sections |
| GET | `/sellers/{id}/products` | Seller product grid |

### Bearer token required (`auth:sanctum`)

| Method | Path | Purpose |
|---|---|---|
| GET | `/favorites` | My favorites |
| POST | `/favorites/{productId}` | Add favorite |
| DELETE | `/favorites/{productId}` | Remove favorite |
| GET | `/my-products` | Seller's listings |
| GET | `/my-products/form` | Live form configuration |
| GET | `/my-products/{id}` | Seller's listing detail |
| POST | `/my-products` | Submit listing |
| PUT | `/my-products/{id}` | Edit listing |
| POST | `/my-products/{id}/status` | Change listing status |

**Correction:** route source enumerates **24 endpoints** (15 public + 9 authenticated); no endpoint is inferred from the file name alone. `{id}` and `{productId}` are numeric. `GET /catalog/products/{id}` is throttled to 120/min; favorite writes 60/min; seller writes 30/min.

## Shared product list contract — verified from `ListsProducts.php`

`GET /catalog/products`, featured, new arrivals and seller grids share the `productPage` pagination presenter where called. `per_page` defaults to 20, maximum 50. The JSON list envelope is:

```json
{
  "data": [{"id": 123, "name": "Example", "cover_image_url": null, "price": {"amount": "50.00", "currency": "SAR"}, "status": "published", "is_favorite": false}],
  "links": {"first": "...", "last": "...", "prev": null, "next": null},
  "meta": {"current_page": 1, "from": 1, "last_page": 1, "per_page": 20, "to": 1, "total": 1, "total_label": "..."}
}
```

The row above is an **illustrative partial projection**, not a complete fixture. Actual card fields are in the table below.

### Product card fields — verified from `ProductViews::card()`

| Field | Type | Nullable | Meaning |
|---|---|---|---|
| `id` | integer | No | Product ID |
| `name` | string | No | Product name |
| `cover_image_url` | string | Yes | Public image URL |
| `price` | object `{amount:string,currency:string}` | No | Decimal money |
| `old_price` | money object | Yes | Original price |
| `discount_percent` | integer | Yes | Discount percentage |
| `discount_label` | string | Yes | Localized discount label |
| `category` | object `{id,name}` | Yes | Category |
| `condition` | lookup object | Yes | Condition |
| `times_used` | integer | No | Usage count |
| `times_used_label` | string | No | Localized usage |
| `meta_line` | string | No | Display summary |
| `size` | string | Yes | Size |
| `brand` | object | Yes | Brand choice |
| `city` | object | Yes | City |
| `status` | string | No | Product status |
| `badge` | object `{key,label}` | Yes | Status badge |
| `purchasable` | boolean | No | Purchase eligibility |
| `can_favorite` | boolean | No | Favorite eligibility |
| `is_favorite` | boolean | No | Current viewer's favorite |
| `is_showcase` | boolean | No | Admin showcase listing |
| `seller` | object `{id,display_name}` | Yes | Public seller summary |

**Business rule:** `purchasable=true` only when published, not locked by an order, with a seller and not seller-hidden. Guest viewers have `is_favorite=false`.

### Browse query fields — verified from `ListsProducts::browseRules()`

| Query key | Type | Validation |
|---|---|---|
| `q` | string | max 100 |
| `sort` | enum | `newest`, `price_asc`, `price_desc` |
| `category_id` | integer | optional |
| `brand_id[]`, `city_id[]`, `color_id[]` | integer[] | max 50 entries each |
| `product_type_id[]`, `condition_id[]` | integer[] | max 20 entries each |
| `size[]` | string[] | max 50 entries; each max 20 chars |
| `price_min`, `price_max` | decimal string | `^\d{1,7}(\.\d{1,2})?$` |
| `has_discount` | boolean | optional |
| `per_page` | integer | 1–50; default 20 |

The list normalization accepts both `brand_id[]=1&brand_id[]=2` and `brand_id=1,2` for selected filter arrays. **Endpoint-specific applicability** must be checked against each browse handler before passing all filters to every listing endpoint.

## Favorites — verified from `FavoriteController.php`

| Endpoint | Request | Response data | Notes |
|---|---|---|---|
| `GET /favorites` | `per_page?: integer (1..50, default 20)` | Paginated `ProductViews::favorite` rows | Sorted by favorited time descending; sold and unavailable may remain |
| `POST /favorites/{productId}` | Numeric path ID, empty body | `{product_id:int,is_favorite:true,changed:bool,message:string}` | Idempotent; non-favoritable products can return 422 |
| `DELETE /favorites/{productId}` | Numeric path ID, empty body | `{product_id:int,is_favorite:false,changed:bool,message:string}` | Idempotent even if product no longer visible |

`GET /favorites` uses standard `data`, `links`, `meta`; meta also includes `total_label`, `note`, `empty`. Each row extends a product card with `favorited_at` (ISO string or null), `tap: {opens_product:boolean,message:string|null}`, and a favorite-specific `badge`.

## My products — verified from `MyProductController.php`

### `GET /my-products`

| Query | Type | Rule |
|---|---|---|
| `status` | string | `all`, `published`, `pending_review`, `rejected`, `unavailable`, `hidden`, `sold`, `admin_hidden` |
| `per_page` | integer | 1..50; default 20 |

Response: paginated `data` from `ProductViews::mine()`, `links` and `meta`. `meta` includes `all_count`, `total_label`, `tabs` (`key`, `label`, `count`, `selected`), `counts`, `note`, `empty`. Rows include `id`, `name`, `cover_image_url`, price fields, `status`, `status_label`, `status_line`, `status_line_tone`, `rejection_reason`, `locked_by_order`, `order_ref`, `actions` (`change_status`, `edit`, `resubmit`, `view_order`), and `submitted_at`, `approved_at`, `updated_at`.

### `GET /my-products/form`

Response `data` includes `seller_ready:boolean`, `missing_requirements:array`, `setup_endpoint:string`, `images:{min,max,help,count_label}`, `name:{min,max}`, `description:{max,help}`, `times_used:{min,max,unused_condition_ids}`, `size_other`, `color_other`, `brand_other`, `brand`, `discount:{enabled}`, `price:{max,currency}`, `default_city`, `commission`, `review_required:true`, `defaults:{product_type_id}`, and `sources` URLs for categories, brands, colors, conditions, product types, sizes, cities and media uploads. **Use the returned configuration instead of hardcoding image/discount limits.**

### `POST /my-products` and `PUT /my-products/{id}` — shared `ProductRequest`

| JSON field | Type | Required | Rule |
|---|---|---|---|
| `images` | string[] | Yes | 1..configured `max_images`; every value `^med_[a-f0-9]{32}$` |
| `name` | string | Yes | Domain `NAME_MIN`..`NAME_MAX` |
| `category_id` | integer | Yes | >=1 |
| `size` | string | No | max 20 |
| `size_other` | string | No | Domain `CUSTOM_MAX` |
| `color_id` | integer | Conditional | >=1; required without `color_other` |
| `color_other` | string | Conditional | Domain `OTHER_MAX` |
| `brand_mode` | enum | Yes | `brand`, `none`, `other` (constants to confirm in domain) |
| `brand_id` | integer | Conditional | required for `brand_mode=brand` |
| `brand_other` | string | Conditional | required for `brand_mode=other` |
| `product_type_id` | integer | Yes | >=1 |
| `condition_id` | integer | Yes | >=1 |
| `times_used` | integer | Yes | >=0; upper bound from domain |
| `price` | decimal string | Yes | `^\d{1,6}(\.\d{1,2})?$` |
| `old_price` | decimal string | No | Same price pattern |
| `city_id` | integer | No | >=1 |
| `description` | string | No | Domain `DESCRIPTION_MAX` |

`POST` returns HTTP **201**, `data` = seller detail plus `message` and `sent` (confirmation title/body/steps). `PUT` returns HTTP **200**, seller detail plus `message`; editing submits for review. Another seller's ID is treated as not found (404). Domain-level conditions (category/size compatibility, discount, seller readiness) are additional to these shape validations.

### `GET /my-products/{id}`

Response `data` = `ProductViews::mineDetail()` (all `mine` row fields, plus `images`, `details`, `status_panel`, `stats`, `show_stats`, `note`, `commission`, `status_sheet`, `edit_banner`, `form`). `details` includes category, size, color, brand, condition, times used, product type, city, description.

### `POST /my-products/{id}/status`

| JSON field | Type | Required | Rule |
|---|---|---|---|
| `status` | string | Yes | One of domain `ProductStatus::SELLER_TOGGLES` |

Response `data` = `mineDetail` plus `changed:boolean` and localized `message:string`. This operation is idempotent for unchanged status.

## Guest category tree — verified from `CatalogController::categories()`

`GET /catalog/categories` returns `{data:[...category nodes],meta:{total:int,total_label:string}}`. Every node extends the category presenter with piece count fields and `children` (recursive array). Only active categories under active ancestors are shown.

`GET /catalog/categories/{id}` returns category data plus `parent`, `children`, `brands`, `filter_sizes`, `name_definite`, `search_placeholder`, `filter_sheet`. The filter sheet contains localized headings, sort options and `price_range:{min,max,step,currency,max_label,all_label,range_label}`. The maximum slider value means **no upper price ceiling**; omit `price_max` rather than submitting the slider maximum.

## Completion gate / remaining source verification

The following are **not yet fully contract-verified** and must not be marked complete: exact presenter shapes for category/brand/lookup/size scale, popular searches, banners, home sections, product detail, featured/new-arrival endpoint-specific metadata, seller grid; full domain enum constants and max lengths; localized error code/status matrix. This file documents verified subsets without inventing the missing fields. Staging contract tests have not been executed.

### Reviewed source files

- `modules/Catalog/Routes/api.php`
- `modules/Catalog/Interfaces/Http/Controllers/{CatalogController,FavoriteController,MyProductController,ProductBrowseController,HomeController}.php`
- `modules/Catalog/Interfaces/Http/Controllers/Concerns/ListsProducts.php`
- `modules/Catalog/Interfaces/Http/Requests/ProductRequest.php`
- `modules/Catalog/Interfaces/Http/Presenters/ProductViews.php`


## Flutter Catalog — controller-verified endpoint contracts (continuation)

**Source of truth:** [`CatalogController.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/CatalogController.php), [`ProductBrowseController.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/ProductBrowseController.php), [`HomeController.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/HomeController.php), [`Presenter.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenter.php). All routes below use `/api/v1` prefix. The JSON examples are structural examples, not recorded staging responses.

### Shared response models

**`AppCategory`** (all fields returned by `Presenter::category`):

| Field | JSON type | Nullable | Notes |
|---|---|---|---|
| `id` | integer | No | Category ID |
| `parent_id` | integer | Yes | Null for root |
| `slug` | string | No | URL slug |
| `name` | string | No | Resolved to request locale with fallback |
| `image_url` | string | Yes | Temporary signed media URL; cache respecting expiry |
| `size_requirement` | string | No | `required`, `optional`, `none` |
| `size_scale_id` | integer | Yes | Size scale reference |
| `sort` | integer | No | Admin sort position |

**`AppBrand`** (`Presenter::brand`):

| Field | JSON type | Nullable | Notes |
|---|---|---|---|
| `id` | integer | No | Brand ID |
| `name` | string | No | Brand name |
| `ar_alias` | string | Yes | Search alias, not display translation |
| `logo_url` | string | Yes | Signed media URL |
| `display_name` | string | No | Same as `name` |

**`AppLookupItem`** (`Presenter::lookupItem`): `id:int`, `label:string` (localized), and **only for the `colors` list** `hex:string|null`. **`AppSizeScale`**: `id:int`, `name:string` (localized), `values:string[]`. **`ProductCount`**: `product_count:int`, `product_count_label:string` (localized).

### GET `/catalog/categories` — public category tree

**Request:** no query/body parameters in the controller. **200 response:** `{data: AppCategoryTreeNode[], meta:{total:int,total_label:string}}`; each tree node is `AppCategory + ProductCount + {children: AppCategoryTreeNode[]}`. `meta.total` counts **all visible nodes**, including descendants. Only active categories whose ancestors are active are included. Children and roots are ordered by `sort`, then `id`.

```json
{"data":[{"id":1,"parent_id":null,"slug":"dresses","name":"Dresses","image_url":null,"size_requirement":"required","size_scale_id":2,"sort":0,"product_count":5,"product_count_label":"5 items","children":[]}],"meta":{"total":1,"total_label":"1 category"}}
```

### GET `/catalog/categories/{id}` — category landing and filter sheet

| Input | Type | Rule |
|---|---|---|
| `id` (path) | integer | Existing category visible in app |

**200 `data`**: `AppCategory + ProductCount` plus the following:

| Field | Type | Description |
|---|---|---|
| `parent` | `{id:int,name:string}` or null | Parent category |
| `children` | `(AppCategory + ProductCount)[]` | Active immediate children |
| `brands` | `(AppBrand + ProductCount)[]` | Active, browsable brands with visible products; most pieces first |
| `filter_sizes` | `string[]` | Empty when size policy `none`, no scale, or fewer than two scale values |
| `name_definite` | string | Category name with definite article, falling back to `name` |
| `search_placeholder` | string | Localized UI text |
| `filter_sheet` | object | Filter sheet labels and controls below |

`filter_sheet` fields: `title:string`, `sort_title:string`, `sort_options:{value:string,label:string,selected:boolean}[]`, `size_title:string`, `price_title:string`, `price_range:{min:number,max:number,step:number,currency:string,max_label:string,all_label:string,range_label:string}`, `city_title:string`, `product_type_title:string`, `product_type_hint:string`, `all_label:string`, `clear_label:string`. Sort values: `newest`, `price_asc`, `price_desc`. **Do not send `price_max` when the slider is at its maximum**: the maximum represents an unbounded upper range. **404** `category_not_found` for nonexistent or nonvisible category.

### GET `/catalog/categories/{id}/brand-options` — product form brand picker

| Query/path field | Type | Validation / use |
|---|---|---|
| `id` (path) | integer | Existing category; inactive allowed for editing old products |
| `q` | string | Optional, max 100; matches name/Arabic alias |
| `current_brand_id` | integer | Optional, >=1; saved brand being edited |
| `current_category_id` | integer | Optional, >=1; saved category being edited |

**200 `data`**:

| Field | Type | Description |
|---|---|---|
| `category` | `{id:int,name:string}` | Selected category |
| `title`, `placeholder`, `search_placeholder`, `most_used_title`, `all_title`, `no_match` | string | Localized UI copy |
| `most_used` | `BrandOption[]` | Up to 8 offered brands with product counts, sorted by usage |
| `brands` | `BrandOption[]` | All active offered brands sorted by normalized name |
| `none` | `{mode:string,label:string}` | No-brand choice |
| `other` | `{mode:string,label:string,prompt:string,placeholder:string,save:string,max:int}` | Custom-brand choice |
| `current` | `CurrentBrandOption|null` | Saved brand verdict, null if missing/not provided |

`BrandOption`: `{mode:string,id:int,name:string,ar_alias:string|null,display_name:string,logo_url:string|null}`. `CurrentBrandOption` adds `offered:boolean`, `keep_allowed:boolean`, `reason:'not_in_category'|'brand_inactive'|null`, `notice:string|null`. `keep_allowed` is true if saved category is unchanged **or** brand is still offered in selected category; the app should obey server flags instead of recomputing rules. **404** `category_not_found`; **422** `validation_failed` for invalid query.

### GET `/catalog/brands` — active brand directory

| Query | Type | Validation |
|---|---|---|
| `q` | string | Optional, max 100 |
| `with_products` | boolean | Optional; true excludes brands with zero visible products |
| `category_id` | integer | Optional, >=1; must be visible |

**200:** `{data:(AppBrand + ProductCount)[],meta:{total:int,total_label:string,category_id:int|null,empty:string|null}}`. Brands are active, filtered by whether shown/browsable in the selected category, ordered by admin `sort` then name. `empty` is localized when no rows. **404** `category_not_found` for invalid/invisible category; **422** validation errors.

### GET `/catalog/brands/{id}` — brand landing

**Input:** integer path `id`; active brand required. **200 `data`:** `AppBrand + ProductCount` plus `search_placeholder:string`, `heading:string`, `is_general:boolean`, `categories:BrandCategoryChip[]`. `BrandCategoryChip` = `{id:int,parent_id:int|null,name:string,linked:boolean,product_count:int,product_count_label:string}`. Categories follow category tree order, including offered categories and visible categories containing this brand's products. **404** `brand_not_found` for missing/inactive brand.

### GET `/catalog/lists/{key}` — active lookup items

**Input:** `key` path string naming a supported fixed lookup list. **200:** `{data:AppLookupItem[]}` ordered by `sort`, then `id`; inactive items excluded. Color items include `hex`, other lists do not. **404** `lookup_list_not_found` for unsupported key. The list keys are fixed in the domain; do not assume arbitrary keys are supported.

### GET `/catalog/size-scales` — size scale options

**Request:** no query/body fields. **200:** `{data:AppSizeScale[]}` ordered by ID. The controller does not apply an active filter. Example:

```json
{"data":[{"id":2,"name":"Clothing sizes","values":["S","M","L"]}]}
```

### GET `/home/banners` — currently displayable home banners

**Request:** no query/body. **200:** `{data:AppBanner[]}`. `AppBanner` is:

| Field | Type | Nullable | Notes |
|---|---|---|---|
| `id` | integer | No | Banner ID |
| `eyebrow` | string | Yes | Localized short line |
| `title` | string | No | Localized headline |
| `subtitle` | string | Yes | Localized supporting text |
| `cta_label` | string | No | Localized text; default translated CTA if unset |
| `theme` | string | No | `light` or `dark` |
| `image_url` | string | Yes | Signed media URL |
| `target` | object | No | `{type:'url',url:string}` or `{type:'category'|'brand',id:int}` |

Only `is_active=true` and `starts_at <= now < ends_at` (null boundary means open-ended) are returned. Banners pointing to inactive/hidden categories or inactive brands are excluded. Order: `sort`, then `id`. Schedule fields are **not** returned to the Flutter app.

### GET `/home/sections` — home product sections

**Request:** no query/body. **200:** `{data:{featured:HomeSection,new_arrivals:HomeSection}}`. Each `HomeSection` contains the translated section labels returned by `catalog::products.sections.*`, plus `items:ProductCard[]`, `see_all:string`. `featured.see_all='/api/v1/catalog/featured'`; `new_arrivals.see_all='/api/v1/catalog/new-arrivals'`. Both use server-configured `homeSectionSize`. Featured selection prioritizes admin featured items and, when authenticated, categories from the viewer's favorites; new arrivals are ordered newest first. Product cards use `ProductViews::card` (see table above). **Do not assume a fixed section size.**

### GET `/catalog/featured` and GET `/catalog/new-arrivals`

| Query | Type | Validation |
|---|---|---|
| `category_id` | integer | Optional |
| `q` | string | Optional, max 100 |
| `per_page` | integer | Optional, 1..50; default 20 from shared pagination |

**200:** paginated `{data:ProductCard[],links:PaginationLinks,meta:PaginationMeta + {count_label:string,empty:{title:string,body:string}}}`. Featured prioritizes curated products and favorite categories; new arrivals sorts newest first. Both apply category subtree filtering and free-text search. `empty` and `count_label` are localized. **Do not send the full browse filters to these endpoints**: their validators accept only the fields above.

### GET `/catalog/search/popular` — popular search chips

**Request:** no query/body. **200:** `{data:{term:string,folded:string,searches:int}[]}`. Only terms with `avg_results > 0` are returned. Count and lookback period come from `ProductSettings` (`popular_searches_limit`, `popular_searches_days`). `term` is display spelling **and** the value to send as `q`; `folded` is normalized text. Example:

```json
{"data":[{"term":"فساتين","folded":"فساتين","searches":18}]}
```

### GET `/catalog/products` — browse response metadata

Uses the browse query table and product card contract earlier in this file. **200** paginated response adds these `meta` fields beyond standard pagination:

| Field | Type | Meaning |
|---|---|---|
| `sort` | string | Applied sort |
| `sort_label` | string | Localized applied sort |
| `sort_options` | `{value:string,label:string,selected:boolean}[]` | Sort picker |
| `active_filters` | integer | Number of active filter groups, not individual values |
| `heading` | string or null | Brand/category heading when one brand is selected |
| `apply_label` | string | Localized apply button with result count |
| `empty` | `{title:string,body:string|null}` | Contextual empty-state UI |
| `results_label` | string | Present only for nonempty `q` |
| `results_title` | string or null | Present only for nonempty `q` |

**Search analytics side effect:** nonempty search is recorded on page 1 when normalized query has at least two characters; successful searches also record spelling. `sort` supports `newest`, `price_asc`, `price_desc`.

### GET `/catalog/products/{id}` — public product detail

**Input:** integer `id`. **200:** `{data:ProductViews::detail(...)}` (full detail nested field matrix remains subject to `ProductViews` verification). Only visible products are returned. Viewing increments a counter **except** for the seller's own view and repeat views within `products.view_dedupe_minutes` (viewer ID, or guest IP + user-agent fingerprint). **404** for missing/nonvisible product. **Do not treat a reload as a guaranteed view increment.**

### GET `/sellers/{id}/products` — seller public grid

**Input:** integer seller `id`; `per_page` follows shared product pagination. **200:** standard paginated `ProductCard[]` with `meta.empty` localized. Only visible seller products in `published`/`unavailable` status are considered, newest approved/created first. Missing public seller profile yields product-not-found business exception (HTTP 404, exact error code to verify).

### Error envelope for the endpoints above

The global [`ApiExceptionRenderer.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/Interfaces/Http/ApiExceptionRenderer.php) emits:

```json
{"error":{"code":"validation_failed","message":"Localized validation message","details":{"q":["Validation message"]},"request_id":null}}
```

| Status | `error.code` | When |
|---|---|---|
| 401 | `unauthenticated` | Protected endpoint without authentication |
| 403 | `forbidden` | Permission denied |
| 404 | `category_not_found`, `brand_not_found`, `lookup_list_not_found` | Domain-specific missing entities |
| 422 | `validation_failed` | Invalid request fields; `details` maps field names to messages |
| 429 | `too_many_attempts` | Throttled; `details.retry_after` seconds |
| 500 | `server_error` | Unexpected production failure |

The response always includes `error.code`, `error.message`, and `error.request_id` (nullable); `error.details` is optional. App must branch on stable codes, not translated messages.

**Verification still outstanding:** full nested `ProductViews::detail` field-by-field contract, `ProductViews::mineDetail` nested structures, exact seller domain error code, complete product-domain validation constraints and all runtime Staging tests. These are explicitly not certified by this continuation.

---

## Product presenter verification — buyer and seller nested contracts (2026-11-22)

Source: [`ProductViews.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenters/ProductViews.php), [`ListsProducts.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Concerns/ListsProducts.php), [`ProductBrowseController.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/ProductBrowseController.php). This section supersedes earlier statements that the nested buyer product response was unverified.

### `GET /catalog/products/{id}` — complete additional fields beyond `ProductCard`

**Path:** `id` integer. **Authentication:** optional. **Success:** HTTP 200, `{ "data": ProductDetail }`. The `ProductDetail` contains all `ProductCard` fields described earlier, except that `seller` is replaced by the richer seller object below.

| JSON path | Type | Nullable | Contract |
|---|---|---|---|
| `data.images` | array of objects | No | Product media, in display order |
| `data.images[].position` | integer | No | One-based index |
| `data.images[].is_cover` | boolean | No | First image is cover |
| `data.images[].url` | string | Yes | Temporary signed media URL |
| `data.color` | object | No | `{id:integer|null,label:string|null,hex:string|null}` |
| `data.product_type` | object | Yes | `{id:integer,label:string|null}` |
| `data.description` | string | Yes | Seller description |
| `data.seller` | object | Yes | Null for showcase or unavailable public profile |
| `data.seller.id` | integer | No (when seller exists) | Public seller user ID |
| `data.seller.display_name` | string | No | Seller display name |
| `data.seller.initial` | string | No | First character of display name |
| `data.seller.avatar_url` | string | Yes | Profile image |
| `data.seller.rating_avg` | number | Depends on profile | Seller average rating |
| `data.seller.rating_count` | integer | No | Rating count |
| `data.seller.rating` | object | Depends on ratings port | Rich rating block, contract owned by Accounts rating presenter |
| `data.seller.meta_line` | string | No | Localized rating/city line |
| `data.seller.listed_count` | integer | No | Seller's listed pieces |
| `data.seller.city` | object | Yes | `{id:integer,name:string}` |
| `data.is_own` | boolean | No | Viewer owns listing |
| `data.availability` | object | No | Server-decided action availability |
| `data.availability.state` | enum string | No | `showcase`, `sold`, `unavailable`, `reserved`, `own`, `available` |
| `data.availability.purchasable` | boolean | No | True only for `available` |
| `data.availability.can_add_to_cart` | boolean | No | True only for `available` |
| `data.availability.can_buy_now` | boolean | No | True only for `available` |
| `data.availability.can_favorite` | boolean | No | True only for `available` |
| `data.availability.note` | string | No | Localized explanation |
| `data.availability.image_badge` | string | Yes | For unavailable/showcase |
| `data.availability.button_label` | string | Yes | Non-available CTA text |
| `data.availability.show_popup` | boolean | No | True for showcase |
| `data.availability.popup` | object | Yes | Showcase `{title:string,body:string}`; otherwise null |
| `data.published_at` | ISO-8601 string | Yes | Approval time, falling back to creation time |

**Behavior:** Flutter must use `availability.can_add_to_cart`, `can_buy_now`, and `can_favorite` instead of recomputing availability from status. `showcase` is not purchasable. The product's own seller cannot buy/favorite their own listing. **404:** `product_not_found` for missing or not visible. Views are deduplicated per viewer for a configured window.

### Product card — verified nested shapes and pricing

| JSON path | Type | Nullable | Notes |
|---|---|---|---|
| `price.amount` | string | No | Decimal formatted amount, not floating point |
| `price.currency` | string | No | Currency code |
| `old_price` | money object | Yes | Same shape as `price` |
| `brand.kind` | string | No | Brand choice mode |
| `brand.id` | integer | Yes | Linked brand ID |
| `brand.name` | string | No | Brand name, other-brand text or localized no-brand label |
| `category.id` | integer | Yes (category object) | Category identifier |
| `category.name` | string | Yes (category object) | Localized display name |
| `condition.id` | integer | Yes (condition object) | Lookup ID |
| `condition.label` | string | Yes | Localized text |
| `city.id` | integer | No (city object) | City identifier |
| `city.name` | string | No (city object) | Localized city name |
| `badge.key` | string | No (badge object) | `unavailable`, `sold`, `reserved` |
| `badge.label` | string | No (badge object) | Localized badge text |
| `seller.id` | integer | No (seller object) | Seller identifier |
| `seller.display_name` | string | No (seller object) | Display name |

**Price display:** `discount_percent` and `discount_label` are nullable. The presenter suppresses `discount_label` when a status badge is displayed. Money amounts must be parsed as decimal strings.

### `GET /my-products/{id}` — seller detail presenter contract

The endpoint's response is `{ "data": SellerProductDetail }`. `SellerProductDetail` includes `SellerProductRow` fields plus the following verified nested objects. The route's auth requirement remains `auth:sanctum`.

| JSON path | Type | Nullable | Meaning |
|---|---|---|---|
| `data.images[]` | array | No | `{position:int,is_cover:bool,url:string|null}` |
| `data.details` | object | No | Current listing fields for status page |
| `data.details.category` | object | Yes | `{id,name}` |
| `data.details.size` | string | Yes | Selected size |
| `data.details.color` | object | No | `{id,label,hex}` nullable members |
| `data.details.brand` | object | No | `{kind,id,name}` |
| `data.details.condition` | object | Yes | `{id,label}` |
| `data.details.times_used` | integer | No | Usage count |
| `data.details.times_used_label` | string | No | Localized short usage label |
| `data.details.product_type` | object | Yes | `{id,label}` |
| `data.details.city` | object | Yes | `{id,name}` |
| `data.details.description` | string | Yes | Description |
| `data.status_panel` | object | No | `{tone,title,body,reason_label,reason,steps}` |
| `data.status_panel.steps` | array | Yes | Review steps, only for `pending_review`; entries `{key,label,hint,at,state}` |
| `data.stats` | object | No | `{views:int,favorites:int}` |
| `data.show_stats` | boolean | No | True only for `published` |
| `data.note` | string | Yes | Localized contextual note |
| `data.commission` | object | No | Pricing-port generated fields; do not infer keys without `CommissionPreview` |
| `data.status_sheet.current` | string | No | Current status |
| `data.status_sheet.options[]` | array | No | `{value,label,hint,selected}` seller toggle choices |
| `data.status_sheet.note` | string | No | Localized guidance |
| `data.edit_banner` | object | Yes | `{title:string,body:string}` |
| `data.form` | object | No | Request-prefill values; field list below |

`data.form` keys: `name`, `category_id`, `brand_mode`, `brand_id`, `brand_other`, `product_type_id`, `condition_id`, `times_used`, `color_id`, `color_other`, `size`, `size_other`, `city_id`, `description`, `price`, `old_price`, `images`. `price` and `old_price` are decimal **strings** (old price nullable); `images` is the stored array of media references, not the signed image URLs. If a custom size was used, `size=null` and `size_other` contains the custom size.

### `GET /my-products` — seller row fields

| Field | Type | Nullable | Meaning |
|---|---|---|---|
| `id` | integer | No | Product ID |
| `name` | string | No | Product name |
| `cover_image_url` | string | Yes | Signed image URL |
| `price`, `old_price` | money object | `old_price` yes | Decimal amounts |
| `discount_percent`, `discount_label` | integer/string | Yes | Discount |
| `status`, `status_label`, `status_line`, `status_line_tone` | string | No | Server-formatted status UI |
| `rejection_reason` | string | Yes | Reason when rejected |
| `locked_by_order` | boolean | No | Order lock |
| `order_ref` | string | Yes | Active or completed order reference |
| `actions.change_status`, `actions.edit`, `actions.resubmit`, `actions.view_order` | boolean | No | Server-computed actions |
| `submitted_at`, `approved_at`, `updated_at` | ISO-8601 string | Yes | Timestamps |

**Action rules:** Editing is blocked when locked by an order. `edit` is false during review and for rejected products; rejected products can expose `resubmit` instead. The server decides whether `view_order` is available. Flutter must not derive these flags independently.

### Buyer list query validation and pagination — exact limits

| Parameter | Type | Constraint |
|---|---|---|
| `q` | string | max 100 |
| `sort` | enum | `newest`, `price_asc`, `price_desc` |
| `category_id` | integer | optional |
| `brand_id`, `city_id`, `color_id` | integer[] | max 50 each |
| `product_type_id`, `condition_id` | integer[] | max 20 each |
| `size` | string[] | max 50, each max 20 |
| `price_min`, `price_max` | decimal string | 1–7 integer digits, optional 1–2 decimals |
| `has_discount` | boolean | optional |
| `per_page` | integer | 1–50; default 20 |

For list query keys, both `brand_id[]=1&brand_id[]=2` and `brand_id=1,2` are accepted (also city, type, condition, color, size). The server uses the standard `{data,links,meta}` paginated envelope. A `per_page` above 50 is capped by `productPage` where that helper is used; `/catalog/products` validates it and can return 422 for out-of-range input.

### Product domain error code

`ProductNotFound` implements `ResourceNotFound` and the global API renderer maps it to **HTTP 404** with `error.code="product_not_found"`. This includes inaccessible products and missing public seller profiles in the browse controller. Standard validation failures are HTTP 422, `error.code="validation_failed"`, with `error.details` keyed by field.




## Seller write operations — complete source-level contract

Sources: `MyProductController.php`, `Requests/ProductRequest.php`, `ProductDetails.php`, `BrandChoice.php`, `ColorChoice.php`, `SizeChoice.php`, `ProductStatus.php`, `SellerProductService.php` (service outcomes are represented by the controller), `LocalizeCatalogErrors.php`.

### `POST /my-products` — create and submit for review

**Auth:** `auth:sanctum`. **Throttle:** 30 writes/minute. **Body:** JSON. **Success:** HTTP **201** `{ "data": <MyProductDetail with message and sent> }`. Submission starts at `pending_review`; there is no client-side direct publication. A seller missing required setup receives the `seller_not_ready` business error with `error.details.missing` and `error.details.setup_endpoint="/api/v1/me/seller-profile"`.

### `PUT /my-products/{id}` — edit and resubmit

**Auth:** `auth:sanctum`; seller owns `{id}`. **Throttle:** 30/min. **Body:** the **same full ProductRequest** as POST (not PATCH; don't send only changed fields). **Success:** HTTP **200** `{ "data": <MyProductDetail with message> }`. Edit sends the listing for review; admin-locked/removed or order-locked records cannot be edited. An ID not owned by the caller is indistinguishable from a missing ID (`404 product_not_found`).

### POST and PUT request fields (`ProductRequest::rules`)

| JSON field | Type | Required | Validation / semantics |
|---|---|---|---|
| `images` | string[] | Yes | 1..configured `max_images` entries, each `med_` + exactly 32 lowercase hexadecimal chars; first image is cover; no duplicate references; live min/max in `GET /my-products/form` |
| `name` | string | Yes | 3..60 characters; whitespace normalized |
| `category_id` | integer | Yes | >=1; must accept listings |
| `size` | string/null | Conditional | max 20; scale value when category requires/permits size; omit for size-less category |
| `size_other` | string/null | Conditional | max 12; custom size; must be supplied when custom-size option is selected |
| `color_id` | integer/null | Conditional | >=1; required without `color_other`; must be active/available |
| `color_other` | string/null | Conditional | max 20; free-text color alternative |
| `brand_mode` | enum string | Yes | `brand`, `none`, `other` |
| `brand_id` | integer/null | When `brand_mode=brand` | >=1; must be allowed for category |
| `brand_other` | string/null | When `brand_mode=other` | max 40; nonblank |
| `product_type_id` | integer | Yes | >=1; active lookup |
| `condition_id` | integer | Yes | >=1; active lookup |
| `times_used` | integer | Yes | 0..99; some conditions require zero |
| `price` | decimal string | Yes | regex `^\d{1,6}(\.\d{1,2})?$`; domain requires >0, <=999999.99 SAR |
| `old_price` | decimal string/null | No | same regex; if supplied must be greater than `price`; discount feature must be enabled |
| `city_id` | integer/null | Conditionally required by domain | >=1; if omitted, server may use seller city; domain requires a valid city |
| `description` | string/null | No | max 500 |

**Example request (illustrative IDs/media reference; substitute actual uploaded media):**

```json
{
  "images": ["med_0123456789abcdef0123456789abcdef"],
  "name": "Evening dress", "category_id": 12,
  "size": "M", "size_other": null,
  "color_id": 4, "color_other": null,
  "brand_mode": "none", "brand_id": null, "brand_other": null,
  "product_type_id": 2, "condition_id": 3, "times_used": 1,
  "price": "150.00", "old_price": null,
  "city_id": 1, "description": "Clean and ready to wear"
}
```

**Response additions:** `POST` returns `data.message:string`, `data.sent:{title:string,body:string,next_title:string,steps:{n:int,title:string,body:string}[],my_products_label:string,add_another_label:string}` alongside every field from `GET /my-products/{id}`. `PUT` adds only `data.message:string` to that detail. The full `data.form` object returned by detail is the canonical edit prefill, not an upload payload of image URLs.

### `POST /my-products/{id}/status` — visibility switch

**Auth:** `auth:sanctum`; seller-scoped. **Throttle:** 30/min. **Body:**

```json
{"status":"unavailable"}
```

| Field | Type | Required | Allowed values |
|---|---|---|---|
| `status` | string | Yes | `published`, `unavailable`, `hidden` |

**Success:** HTTP 200 `{ "data": <MyProductDetail plus changed:boolean and message:string> }`. `changed=false` means the idempotent request did not transition state. This endpoint **does not** approve rejected or pending-review products and cannot override platform locks. Render available actions from `data.actions.change_status` and options from `data.status_sheet.options`, not from hard-coded client rules.

### `GET /my-products` — exact seller list filters and meta

| Query | Type | Constraint |
|---|---|---|
| `status` | string | `all`, `published`, `pending_review`, `rejected`, `unavailable`, `hidden`, `sold`, `admin_hidden`; default `all` |
| `per_page` | integer | 1..50; default 20 |
| `page` | integer | Pagination page |

Response `{data:[MyProductRow],links,meta}`; `meta` includes `current_page`, `from`, `last_page`, `per_page`, `to`, `total`, `all_count:int`, `total_label:string`, `tabs:[{key:string,label:string,count:int,selected:boolean}]`, `counts:{all:int,published:int,pending_review:int,rejected:int,unavailable:int,hidden:int,sold:int,admin_hidden:int}`, `note:string`, `empty:string|{title:string,body:null}`. **Important:** `meta.total` is the selected tab's count, while `all_count`/`total_label` describe all seller listings. Removed products are excluded.

### `GET /my-products/form` — runtime settings and dependencies

**Success:** 200 `{data:{...}}`. Source field matrix:

| Field | Type | Meaning |
|---|---|---|
| `seller_ready` | boolean | Seller setup gate |
| `missing_requirements` | array | Unfulfilled seller setup items |
| `setup_endpoint` | string | `/api/v1/me/seller-profile` |
| `images` | object | `{min:int,max:int,help:string,count_label:string}` |
| `name` | object | `{min:3,max:60}` |
| `description` | object | `{max:500,help:string}` |
| `times_used` | object | `{min:0,max:99,unused_condition_ids:int[]}` |
| `size_other` | object | `{max:12,label:string,placeholder:string}` |
| `color_other` | object | `{max:20,label:string,placeholder:string}` |
| `size_optional_label` | string | Optional-size hint |
| `brand_other` | object | `{max:40}` |
| `brand` | object | `{placeholder,choose_category_first,none_label,other_label}` strings |
| `discount` | object | `{enabled:boolean}` |
| `price` | object | `{max:"999999.99",currency:"SAR"}` |
| `default_city` | object/null | `{id:int,name:string}` |
| `city_help`, `product_type_help` | string | Localized help |
| `commission` | object | `{rate:string,rate_label:string,hint:string,preview_endpoint:string,preview_debounce_ms:int}` |
| `commission_fallback` | string | Hint before price entered |
| `review_required` | boolean | Always `true` |
| `prohibited_items_page` | string | `prohibited-items` |
| `prohibited_items` | object | `{title,note,link_label,page}` strings |
| `defaults` | object | `{product_type_id:int|null}` |
| `sources` | object | URL strings for `categories`, `brands`, `brand_options`, `colors`, `conditions`, `product_types`, `size_scales`, `cities`, `upload` |

Use live `images.min/max` and `discount.enabled`; don't assume hard-coded administrative settings. Call `commission.preview_endpoint` with `price`/`old_price` using a **300 ms debounce**; do not calculate commission client-side.

## Complete nested seller, rating, commission and availability fields

Sources: `ProductViews.php`, `CommissionPreview.php`, `Accounts/Infrastructure/LangSellerRatingLabels.php`.

### Buyer detail `GET /catalog/products/{id}` additional fields

The response is `{"data": <ProductCard plus detail fields>}`. In addition to the full card fields documented above:

| Field | Type | Meaning |
|---|---|---|
| `data.images[]` | array | `{position:int,is_cover:boolean,url:string|null}`; positions start at 1 |
| `data.color` | object | `{id:int|null,label:string|null,hex:string|null}` |
| `data.product_type` | object/null | `{id:int,label:string}` |
| `data.description` | string/null | Seller description |
| `data.seller` | object/null | Full seller block below |
| `data.is_own` | boolean | Authenticated viewer owns this product |
| `data.availability` | object | Server-driven action flags below |
| `data.published_at` | ISO timestamp/null | Approval or creation date |

`data.seller` when non-null: `id:int`, `display_name:string`, `initial:string`, `avatar_url:string|null`, `rating_avg:number|null`, `rating_count:int`, `rating:RatingBlock`, `meta_line:string`, `listed_count:int`, `city:{id:int,name:string}|null`.

**RatingBlock** (from Accounts):

| Field | Type | Meaning |
|---|---|---|
| `average` | string/null | One-decimal average, null with no ratings |
| `average_label` | string/null | Localized average |
| `count` | integer | Number of ratings |
| `count_label` | string | Localized rating count |
| `stars_filled` | integer | Rounded star count, 0 when empty |
| `empty` | boolean | No ratings |
| `empty_text` | string/null | Localized empty rating label |
| `label` | string | Full localized rating summary |

**Availability:** `state` enum `available|sold|unavailable|reserved|own|showcase`, `purchasable:boolean`, `can_add_to_cart:boolean`, `can_buy_now:boolean`, `can_favorite:boolean`, `note:string`, `image_badge:string|null`, `button_label:string|null`, `show_popup:boolean`, `popup:{title:string,body:string}|null`. A seller viewing their own product gets `own`; showcase listings have `show_popup=true` and cannot be bought. **Use server action booleans.**

### Seller detail `GET /my-products/{id}` nested commission

`data.commission` is **always** an object with these fields (all source-verified):

| Field | Type | Meaning |
|---|---|---|
| `currency` | string | Money currency |
| `price` | decimal string | Sale/listing price |
| `commission` | decimal string | Platform commission |
| `commission_rate` | string | Commission rate percent |
| `seller_net` | decimal string | Seller's net amount |
| `text` | string | Localized seller net sentence |
| `basis` | enum | `current_rate` or `order_snapshot` |

For a sold product with a frozen Orders sale figure, `basis=order_snapshot` reflects the rate **at payment**, not today's fee rate. Otherwise the current fee policy is used. Seller detail also contains `data.status_panel`, `data.status_sheet`, `data.edit_banner`, `data.form`, `data.stats`, and action flags as documented earlier.

## Favorites — all three endpoints

**Authentication:** Sanctum for all. `GET /favorites` accepts `per_page` 1..50 (default 20) and `page`; response `{data:[FavoriteCard],links,meta}`. A FavoriteCard is the normal ProductCard plus `favorited_at:ISO string|null`, `tap:{opens_product:boolean,message:string|null}`, and a status `badge:{key,label}|null` (`sold`, `unavailable` or null). `meta` adds `total_label:string|null`, `note:string`, `empty:string` to normal pagination. Sold/unavailable favorites may remain listed; hidden, in-review, removed, and seller-hidden listings are excluded.

| Endpoint | Request | HTTP 200 response `data` | Behavior |
|---|---|---|---|
| `POST /favorites/{productId}` | No JSON body | `{product_id:int,is_favorite:true,changed:boolean,message:string}` | Idempotent add; only currently purchasable products; 422 `product_not_favoritable` otherwise |
| `DELETE /favorites/{productId}` | No JSON body | `{product_id:int,is_favorite:false,changed:boolean,message:string}` | Idempotent removal, even when product is no longer visible |

Favorite writes are throttled at **60/minute**. `changed` indicates whether storage changed, not whether the request succeeded.

## Error and business-rule reference for Flutter Catalog

| HTTP | `error.code` | Scenario |
|---|---|---|
| 401 | `unauthenticated` | Missing/invalid Sanctum token on protected route |
| 404 | `product_not_found` | Missing, not visible, or not owned product |
| 422 | `validation_failed` | Laravel request validation; `error.details` keyed by field |
| 422 | `seller_not_ready` | Seller setup incomplete; details contain `missing` and `setup_endpoint` |
| 422 | `product_not_favoritable`, `own_product` | Favorite attempt on ineligible/own item |
| 422 | `product_name_too_short`, `product_name_too_long`, `description_too_long` | Text bounds |
| 422 | `invalid_times_used`, `times_used_must_be_zero` | Usage rules |
| 422 | `invalid_price`, `price_too_high`, `old_price_not_higher`, `discount_disabled` | Price/discount rules |
| 422 | `images_required`, `duplicate_image`, `too_few_images`, `too_many_images` | Media references and counts |
| 422 | `category_not_available`, `brand_required`, `brand_not_available`, `brand_not_in_category`, `brand_other_required`, `brand_other_too_long` | Taxonomy/brand choices |
| 422 | `color_required`, `color_other_too_long`, `size_required`, `size_other_required`, `size_not_allowed`, `size_not_in_scale`, `size_too_long` | Color/size choices |
| 422 | `city_required`, `city_not_available`, `product_reference_required` | Location/reference validation |
| 422 | `product_type_not_available`, `product_condition_not_available`, `color_not_available` | Invalid inactive lookup selections |
| 429 | `too_many_attempts` | Route throttle exceeded |

The Catalog middleware translates business messages into the requested language and, for `ProductRuleViolation` with a field, attaches `error.details[field]=[localized_message]`. Other state/transition failures are service/domain errors; clients must preserve the returned code/message rather than inventing a translation or assuming every 422 belongs to one of the listed examples.

**Standard error example:**

```json
{
  "error": {
    "code": "old_price_not_higher",
    "message": "Localized explanation from the server",
    "request_id": null,
    "details": {"old_price": ["Localized explanation from the server"]}
  }
}
```

## Flutter implementation checklist / source QA

- [x] 24 routes reconciled against `modules/Catalog/Routes/api.php` (15 public, 9 protected).
- [x] Buyer catalog, home, browse, seller browse, popular searches and favorites controller contracts reviewed.
- [x] Seller listing create/update/status request fields, runtime form rules and return shapes reviewed.
- [x] Nested buyer product, seller status, rating, availability and commission shapes reviewed.
- [x] Domain field errors and API error envelope reviewed.
- [ ] Live staging response snapshots, authenticated ownership tests, rate-limit tests and localized error smoke tests **not executed**; required before runtime acceptance.

**Source-level documentation status: complete for the 24 Catalog-owned Flutter routes.** Cross-module dependencies (`/api/v1/media`, `/api/v1/cities`, `/api/v1/fees/seller-net`, seller profile) are intentionally linked as dependencies, not counted as Catalog routes. This is not a claim that staging behavior was tested.
