> **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 — Dashboard

**Source:** `alalmiyalhura/outlet` GitLab `main`, `modules/Catalog/Routes/api.php`. Base path: `/api/v1`.

**Route inventory:** 69 method/path entries. Source-reviewed controller/request contracts are below; staging behavior has not been tested.

## Route index

| # | Method and path |
|---:|---|
| 1 | `GET /admin/catalog/products` |
| 2 | `GET /admin/catalog/products/review-queue` |
| 3 | `POST /admin/catalog/products/showcase` |
| 4 | `GET /admin/catalog/products/{id}` |
| 5 | `GET /admin/catalog/products/{id}/history` |
| 6 | `GET /admin/catalog/products/{id}/versions` |
| 7 | `POST /admin/catalog/products/{id}/approve` |
| 8 | `POST /admin/catalog/products/{id}/reject` |
| 9 | `PUT /admin/catalog/products/{id}` |
| 10 | `POST /admin/catalog/products/{id}/hide` |
| 11 | `POST /admin/catalog/products/{id}/unhide` |
| 12 | `POST /admin/catalog/products/{id}/remove` |
| 13 | `POST /admin/catalog/products/{id}/restore` |
| 14 | `GET /admin/catalog/featured` |
| 15 | `PUT /admin/catalog/featured` |
| 16 | `POST /admin/catalog/featured` |
| 17 | `GET /admin/catalog/featured/history` |
| 18 | `DELETE /admin/catalog/featured/{productId}` |
| 19 | `GET /admin/catalog/product-settings` |
| 20 | `PATCH /admin/catalog/product-settings` |
| 21 | `GET /admin/catalog/product-settings/history` |
| 22 | `GET /admin/catalog/categories` |
| 23 | `POST /admin/catalog/categories` |
| 24 | `GET /admin/catalog/brands` |
| 25 | `POST /admin/catalog/brands` |
| 26 | `GET /admin/catalog/lists` |
| 27 | `GET /admin/catalog/size-scales` |
| 28 | `POST /admin/catalog/size-scales` |
| 29 | `GET /admin/catalog/categories/{id}` |
| 30 | `PUT /admin/catalog/categories/{id}` |
| 31 | `GET /admin/catalog/brands/{id}` |
| 32 | `PUT /admin/catalog/brands/{id}` |
| 33 | `GET /admin/catalog/size-scales/{id}` |
| 34 | `PUT /admin/catalog/size-scales/{id}` |
| 35 | `POST /admin/catalog/categories/reorder` |
| 36 | `GET /admin/catalog/categories/{id}/history` |
| 37 | `POST /admin/catalog/categories/{id}/activate` |
| 38 | `POST /admin/catalog/categories/{id}/deactivate` |
| 39 | `POST /admin/catalog/brands/reorder` |
| 40 | `GET /admin/catalog/brands/{id}/history` |
| 41 | `POST /admin/catalog/brands/{id}/activate` |
| 42 | `POST /admin/catalog/brands/{id}/deactivate` |
| 43 | `GET /admin/catalog/categories/{id}/brands` |
| 44 | `PUT /admin/catalog/categories/{id}/brands` |
| 45 | `PUT /admin/catalog/categories/{id}/image` |
| 46 | `PUT /admin/catalog/brands/{id}/categories` |
| 47 | `PUT /admin/catalog/brands/{id}/logo` |
| 48 | `GET /admin/catalog/size-scales/{id}/history` |
| 49 | `GET /admin/catalog/lists/{key}` |
| 50 | `POST /admin/catalog/lists/{key}` |
| 51 | `POST /admin/catalog/lists/{key}/reorder` |
| 52 | `GET /admin/catalog/lists/{key}/{id}` |
| 53 | `PUT /admin/catalog/lists/{key}/{id}` |
| 54 | `GET /admin/catalog/lists/{key}/{id}/history` |
| 55 | `POST /admin/catalog/lists/{key}/{id}/activate` |
| 56 | `POST /admin/catalog/lists/{key}/{id}/deactivate` |
| 57 | `GET /admin/home/banners` |
| 58 | `POST /admin/home/banners` |
| 59 | `POST /admin/home/banners/reorder` |
| 60 | `GET /admin/home/banners/{id}` |
| 61 | `PUT /admin/home/banners/{id}` |
| 62 | `GET /admin/home/banners/{id}/history` |
| 63 | `PUT /admin/home/banners/{id}/image` |
| 64 | `POST /admin/home/banners/{id}/activate` |
| 65 | `POST /admin/home/banners/{id}/deactivate` |
| 66 | `DELETE /admin/home/banners/{id}` |
| 67 | `GET /admin/catalog/settings` |
| 68 | `PATCH /admin/catalog/settings` |
| 69 | `GET /admin/catalog/settings/history` |

---

# Controller-verified contracts: product moderation, featured and product settings

> Verified against `main` source files `ProductAdminController.php`, `FeaturedAdminController.php`, `ProductSettingsController.php`, `ProductRequest.php`, and `ProductViews.php` on 2026-11-22. These sections **supersede the route-only placeholders above for the listed endpoints**. The detailed sections below cover the remaining Catalog controllers; final sign-off still requires staging tests. All paths below are relative to `/api/v1`; all require `Authorization: Bearer <token>` and the indicated permission. This is source verification, **not staging execution**.

## Product list and review queue

| Method/path | Permission | Behavior |
|---|---|---|
| `GET /admin/catalog/products` | `products.view` | Paginated product administration list; default newest created first |
| `GET /admin/catalog/products/review-queue` | `products.review` | Only `pending_review`; default oldest submission first |

### Query contract (both routes)

| Parameter | Type / accepted values | Rules / behavior |
|---|---|---|
| `per_page` | integer | 1–100; default 15 |
| `page` | integer | Laravel paginator page |
| `sort` | string | `created_at`, `submitted_at`, `approved_at`, `status_changed_at`, `price`, `name`, `views`, `favorites`; prefix `-` for descending |
| `filter[search]` | string | Matches product name/text, numeric product ID and matching seller accounts |
| `filter[status]` | string or string[] | Comma-separated or array; each member must match `ProductStatus::values()`; queue still forces pending review |
| `filter[category_id]` | integer IDs | Includes descendants of selected categories |
| `filter[brand_id]`, `filter[seller_id]`, `filter[city_id]` | integer ID(s) | Selection filters |
| `filter[product_type_id]`, `filter[condition_id]`, `filter[color_id]` | integer ID(s) | Selection filters |
| `filter[brand_kind]` | string(s) | `brand`, `none`, `other` |
| `filter[seller_hidden]`, `filter[has_discount]`, `filter[admin_created]`, `filter[locked_by_order]`, `filter[featured]` | boolean-like | Flag filters |
| `filter[created_from]`, `filter[created_to]`, `filter[submitted_from]`, `filter[submitted_to]`, `filter[approved_from]`, `filter[approved_to]` | date | Inclusive day bounds; Laravel `date` validation |
| `filter[decided_by]` | integer | ID ≥ 1; administrator who approved/rejected |
| `filter[price_min]`, `filter[price_max]` | decimal string | Regex `^\d{1,7}(\.\d{1,2})?$` |

### Response (200)

| JSON path | Type | Meaning |
|---|---|---|
| `data` | array<ProductAdminRow> | `ProductViews::admin()` records; see row contract below |
| `links.first`, `links.last` | string | Pagination URLs |
| `links.prev`, `links.next` | string or null | Pagination URLs |
| `meta.current_page`, `meta.last_page`, `meta.per_page`, `meta.total` | integer | Pagination |
| `meta.from`, `meta.to` | integer or null | Item offsets |
| `meta.counts.all` | integer | Count under non-status filters |
| `meta.counts.<status>` | integer | Counts for each product status |
| `meta.counts.seller_hidden`, `meta.counts.locked_by_order`, `meta.counts.brand_to_review` | integer | Additional counters |
| `meta.status_labels` | object | Status → localized labels |

**ProductAdminRow (source: `ProductViews::admin`)**

| Field(s) | Type / shape |
|---|---|
| `id` | integer |
| `name`, `status` | string |
| `cover_image_url` | string or null |
| `price`, `old_price` | `{amount: string, currency: string}`; `old_price` nullable |
| `discount_percent`, `discount_label` | integer or null; string or null |
| `status_label`, `status_before_label` | localized labels object or null |
| `status_before`, `admin_reason`, `locked_order_ref`, `sold_order_ref` | string or null |
| `is_showcase` | boolean |
| `seller` | null or `{id, display_name, phone_masked, account_status, hidden_from_buyers}` |
| `category` | null or `{id, name}`; `name` is localized raw value in admin view |
| `brand` | `{kind, id, name, other, needs_review}` |
| `product_type`, `condition` | null or `{id, label}` |
| `times_used` | integer |
| `color` | `{id, label, other, hex}` with nullable members |
| `size`, `size_custom` | nullable strings |
| `city` | object or null; inspect `cityAdmin()` before binding nested keys |
| `rejection` | null or `{reason_id, reason_label, note}` |
| `views_count`, `favorites_count`, `image_count` | integer |
| `submitted_at`, `approved_at`, `status_changed_at`, `created_at`, `updated_at` | ISO-8601 string or null |

## Product details and audit

| Endpoint | Query/body | Success `data` |
|---|---|---|
| `GET /admin/catalog/products/{id}` | Numeric path `id` | `ProductAdminRow` plus `description`, `images`, `visible_to_buyers`, `purchasable`, `allowed_actions`, `form`, `seller_summary`, `is_featured`, `review_history`, `last_admin_edit`, `last_admin_action`, `links` |
| `GET /admin/catalog/products/{id}/history` | `per_page`: integer 1–100 (default 25); `event`: string max 40 | Paginated audit records via `AuditTrail::respond` |
| `GET /admin/catalog/products/{id}/versions` | `limit`: integer 1–500 (default 100) | `{last_approved: ..., versions: [...]}`; version object shape from persistence needs separate verification |

`allowed_actions` contains boolean keys `approve`, `reject`, `edit`, `hide`, `unhide`, `remove`, `restore`. `review_history[]` includes `decision`, `decision_label`, `reason_id`, `reason`, `actor_id`, `actor`, `at`. `seller_summary` includes `id`, `display_name`, `phone_masked`, `account_status`, `public_profile`, `ready_to_sell`, `missing`, `rating_avg`, `rating_count`, `listed_count`, `products_count`, `account`.

## Product mutations

| Endpoint | Permission | Body validation | Success |
|---|---|---|---|
| `POST /admin/catalog/products/showcase` | `products.create_unavailable` | Complete `ProductRequest` (below) | HTTP 201, `data` = `ProductViews::adminDetail` |
| `PUT /admin/catalog/products/{id}` | `products.edit` | Complete `ProductRequest` (below) | HTTP 200, `data: {changed: boolean, product: ProductAdminDetail}` |
| `POST /admin/catalog/products/{id}/approve` | `products.review` | No validated body | HTTP 200, same mutation response |
| `POST /admin/catalog/products/{id}/reject` | `products.review` | `reason_id`: nullable integer ≥1, required without `note`; `note`: nullable string max `Product::REASON_MAX`, required without `reason_id` | HTTP 200, same mutation response |
| `POST /admin/catalog/products/{id}/hide` | `products.hide` | `reason`: required string, min 3, max `Product::REASON_MAX` | HTTP 200, same mutation response |
| `POST /admin/catalog/products/{id}/unhide` | `products.hide` | No validated body | HTTP 200, same mutation response |
| `POST /admin/catalog/products/{id}/remove` | `products.delete` | `reason`: required string, min 3, max `Product::REASON_MAX` | HTTP 200, same mutation response |
| `POST /admin/catalog/products/{id}/restore` | `products.delete` | No validated body | HTTP 200, same mutation response |

Repeated moderation actions are designed to return `changed: false` when they make no state change; invalid state transitions may still fail under domain rules.

### Complete `ProductRequest` input fields

| Field | Type | Validation |
|---|---|---|
| `images` | array<string> | Required, 1 to configured `max_images` |
| `images[]` | string | `med_` followed by exactly 32 lowercase hexadecimal characters |
| `name` | string | Required; min/max from `ProductDetails` constants |
| `category_id` | integer | Required, ≥1 |
| `size` | string or null | Max 20 |
| `size_other` | string or null | Max `SizeChoice::CUSTOM_MAX` |
| `color_id` | integer or null | ≥1; required without `color_other` |
| `color_other` | string or null | Max `ColorChoice::OTHER_MAX` |
| `brand_mode` | string | Required: `brand`, `none`, `other` |
| `brand_id` | integer or null | ≥1; required if `brand_mode=brand` |
| `brand_other` | string or null | Max `BrandChoice::OTHER_MAX`; required if `brand_mode=other` |
| `product_type_id`, `condition_id` | integer | Required, ≥1 |
| `times_used` | integer | Required, 0 to `ProductDetails::TIMES_USED_MAX` |
| `price` | decimal string | Required, regex `^\d{1,6}(\.\d{1,2})?$` |
| `old_price` | decimal string or null | Same price regex |
| `city_id` | integer or null | ≥1 |
| `description` | string or null | Max `ProductDetails::DESCRIPTION_MAX` |

Additional business validation (category/size suitability, status transitions, price constraints) is enforced beyond this request shape. **Do not assume those checks are absent.**

## Featured products

All endpoints require `products.feature`.

| Endpoint | Request | Success response |
|---|---|---|
| `GET /admin/catalog/featured` | None | `{data: FeaturedItem[], meta: FeaturedMeta}` |
| `PUT /admin/catalog/featured` | `{product_ids: integer[]}` required/present, max `FeaturedList::MAX`, each ≥1 | Same as GET |
| `POST /admin/catalog/featured` | `{product_id: integer, position?: integer|null}`; ID ≥1, position ≥0 | `{data: {changed: boolean, items: FeaturedItem[]}, meta: FeaturedMeta}` |
| `DELETE /admin/catalog/featured/{productId}` | Numeric path ID | Same as POST |
| `GET /admin/catalog/featured/history` | None | `{data: AuditItem[]}`; newest 100 |

| FeaturedItem field | Type |
|---|---|
| `position`, `product_id` | integer |
| `featurable`, `shown_in_app` | boolean |
| `issue` | null or `{key: string, label: object}`; keys `missing`, `not_listed`, `seller_hidden` |
| `product` | null or `ProductAdminRow` |

`FeaturedMeta`: `total`, `max`, `stale_count`, `shown_count` are integers. History item fields: `id`, `event`, `old_values`, `new_values`, `actor_id`, `actor`, `at`. A stale featured item can remain during reorder; `shown_in_app` is authoritative for visibility.

## Product settings

All endpoints require `settings.manage`.

| Endpoint | Request | Success |
|---|---|---|
| `GET /admin/catalog/product-settings` | None | `data` = `ProductSettings::toArray()` |
| `PATCH /admin/catalog/product-settings` | Partial fields below | `data` = settings plus `changed: boolean`, `changes: array` |
| `GET /admin/catalog/product-settings/history` | SettingsHistory query contract requires presenter review | Audit history via `SettingsHistory::respond` |

| PATCH field | Type | Validation |
|---|---|---|
| `min_images`, `max_images` | integer | 1–20; min must not exceed max |
| `show_sold`, `discount_enabled` | boolean | Optional |
| `review_required` | accepted/true | Cannot be turned off |
| `unused_condition_ids` | integer[] | Max 20; IDs must exist in `catalog_lookup_items` for `product_conditions` |
| `showcase_popup_title` | localized object | Max 120 characters per localized value; default language required by localized rule |
| `showcase_popup_body` | localized object | Max 500 characters per localized value |
| `home_section_size`, `popular_searches_limit` | integer | 1–30 |
| `popular_searches_days` | integer | 1–365 |
| `view_dedupe_minutes` | integer | 1–1440 |
| `filter_price_max` | integer | 10–1,000,000 |
| `filter_price_step` | integer | 1–10,000 |
| `default_product_type_id` | integer or null | Existing lookup item in `product_types` |

`422 product_images_range_invalid` is raised when configured minimum images exceeds maximum. Other validation failures use the application's validation response.

## Verification scope

- **All 69 routes:** covered by the route index and controller contract sections in this document.
- **Not runtime-tested:** staging responses, permissions under real roles, and sample payloads.
- Source links: [ProductAdminController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/ProductAdminController.php), [FeaturedAdminController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/FeaturedAdminController.php), [ProductSettingsController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/ProductSettingsController.php), [ProductViews](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenters/ProductViews.php).

## Verified implementation contract — Categories, Brands & Size Scales (2026-11-22)

Source: `modules/Catalog/Routes/api.php`, `Interfaces/Http/Controllers/Admin/{CategoryAdminController,BrandAdminController}.php`, `Interfaces/Http/Requests/{CategoryRequest,BrandRequest,SizeScaleRequest}.php` on GitLab `main`. All routes below require `auth:sanctum`; category and size-scale routes require `can:categories.manage`; brand routes require `can:brands.manage`. Paths are relative to `/api/v1`. The `ApiResponse::ok` endpoints return the payload under `data`; paginated endpoints return top-level `data`, `links`, and `meta`. The route index above is navigational; the contracts here are authoritative.

### Categories — endpoint-by-endpoint contract

| Method and path | Request contract | Response `data` / behavior |
|---|---|---|
| `GET /admin/catalog/categories` | No query fields handled by controller | Array of category objects: base `Presenter::category(..., true)` plus `depth:int`, `visible:bool`, `brands_count:int`, `products_count:int` (includes descendants, all statuses) |
| `POST /admin/catalog/categories` | `CategoryRequest` table below | `201`, created category via `Presenter::category(..., true)` |
| `POST /admin/catalog/categories/reorder` | `ReorderRequest` (see note below) | `204 No Content`; reorders children of specified parent |
| `GET /admin/catalog/categories/{id}` | `id`: positive numeric route parameter | Category object plus `brands_count:int`, `inherited_brands_count:int`, `products:{total:int,by_status:object}`, `links:{brands:string,history:string}` |
| `GET /admin/catalog/categories/{id}/history` | `per_page?:int` 1–100, default 25; `event?:string` max 40 | Paginated `AuditTrail::respond` audit history for category |
| `GET /admin/catalog/categories/{id}/brands` | `id`: numeric | `BrandLinkViews::categoryBrands(...)`: linked/inherited/general brand relationships; nested schema needs separate presenter audit |
| `PUT /admin/catalog/categories/{id}/brands` | `brand_ids`: **present** array of distinct positive integers, max 1000; `[]` permitted | Updated category brand-link view plus `became_category_specific` (brands converted from general to category-specific) |
| `PUT /admin/catalog/categories/{id}` | Full `CategoryRequest` (see table); **not PATCH semantics** | Updated category object |
| `PUT /admin/catalog/categories/{id}/image` | `ImageRequest` media reference (schema needs request audit) | Updated category object |
| `POST /admin/catalog/categories/{id}/activate` | No body | Updated category object |
| `POST /admin/catalog/categories/{id}/deactivate` | No body | Updated category object |

**Category create/update request fields**

| Field | Type | Create | Update (`PUT`) | Validation / semantics |
|---|---|---|---|---|
| `name` | localized map, e.g. `{ "ar": "...", "en": "..." }` | Required | Required | `LocalizedTextRule::max(120)`; default language required |
| `name_definite` | localized map or null | Optional | Optional | `OptionalLocalizedText::max(120)`; used in app sentences |
| `slug` | string | Required | Required | Max 80 |
| `parent_id` | integer or null | Optional | **Must be present** | Positive integer if supplied; `null` means root |
| `size_requirement` | enum string | Required | Required | `required`, `optional`, `none` |
| `size_scale_id` | integer or null | Optional | **Must be present** | Positive integer if supplied; `null` means no scale |
| `sort` | integer | Optional | Required | >= 0; create default 0 |
| `image` | string or null | Optional | Optional | Max 40; media business validation occurs downstream |

**Important:** Sending only changed fields to category `PUT` is invalid; `parent_id`, `size_scale_id`, and `sort` must be explicitly supplied. Domain validation also enforces tree/slug/size policies; exact error mappings require domain exception audit.

### Size scales — endpoint-by-endpoint contract

| Method and path | Request contract | Response `data` / behavior |
|---|---|---|
| `GET /admin/catalog/size-scales` | No query fields handled | Array of `Presenter::scale(..., true)` objects plus `categories_count:int` |
| `POST /admin/catalog/size-scales` | `name` localized map required max 120; `values` required list of 1–60 strings, each max 20 | `201`, `Presenter::scale(..., true)` |
| `GET /admin/catalog/size-scales/{id}` | Numeric ID | Scale object plus `categories_count:int`, `categories:[{id:int,name:localized-map,is_active:bool}]`, `created_at`, `updated_at` ISO 8601 or null, `links.history:string` |
| `GET /admin/catalog/size-scales/{id}/history` | `per_page?:int` 1–100, default 25 | Paginated audit history (`AuditTrail::respond`) |
| `PUT /admin/catalog/size-scales/{id}` | Same required `name` and `values` as POST; full replacement | Updated scale object |

### Brands — endpoint-by-endpoint contract

| Method and path | Request contract | Response `data` / behavior |
|---|---|---|
| `GET /admin/catalog/brands` | `q?:string` max 100; `active?:bool`; `per_page?:int` 1–100, default 50; `filter[...]` and `sort` below | Paginated brand objects with `category_ids:int[]`, `categories_count:int`, `is_general:bool`, plus `links` and `meta` |
| `POST /admin/catalog/brands` | `BrandRequest` table below | `201`, brand detail object |
| `POST /admin/catalog/brands/reorder` | `ReorderRequest` IDs (schema needs request audit) | `204 No Content` |
| `GET /admin/catalog/brands/{id}` | Numeric ID | Brand detail plus linked category information and product status counts |
| `GET /admin/catalog/brands/{id}/history` | `per_page?:int` 1–100 default 25; `event?:string` max 40 | Paginated audit history |
| `PUT /admin/catalog/brands/{id}/categories` | `category_ids`: **present** array, max 500, positive distinct integer items | Updated brand detail; `[]` makes it general/unlinked |
| `PUT /admin/catalog/brands/{id}` | `BrandRequest` table below | Updated brand detail; omitted `category_ids` preserves existing links |
| `PUT /admin/catalog/brands/{id}/logo` | `ImageRequest` media reference (schema needs request audit) | Updated brand detail |
| `POST /admin/catalog/brands/{id}/activate` | No body | Updated brand detail |
| `POST /admin/catalog/brands/{id}/deactivate` | No body | Updated brand detail |

**Brand create/update request fields**

| Field | Type | Validation / semantics |
|---|---|---|
| `name` | string | Required; max 100 |
| `ar_alias` | string or null | Optional; max 100 |
| `sort` | integer | Optional; >= 0; controller defaults to 0 |
| `logo` | string or null | Optional; max 40 |
| `category_ids` | integer[] | Optional; max 500; positive distinct items. Absent on update preserves links; `[]` makes a general brand |

**Brand list filters and sorts**

| Query | Meaning |
|---|---|
| `filter[search]`, `q` | Search normalized brand name or Arabic alias; `q` max 100 |
| `filter[active]`, `active` | Filter active state |
| `filter[category_id]` | Directly linked category; with `filter[inherited]=1` includes inherited links |
| `filter[linked]` | Linked vs general brands |
| `filter[has_logo]` | Has / lacks logo |
| `filter[created_from]`, `filter[created_to]` | Creation date range |
| `sort` | `sort`, `name`, `created_at`, `updated_at`, `categories_count`; prefix `-` for descending |

Brand detail additional keys: `category_ids:int[]`, `categories:array`, `categories_count:int`, `is_general:bool`, `offered_category_ids:int[]|null`, `unlinked_brands_visible:bool`, `products:{total:int,by_status:object}`, `created_at:string|null`, `links:{history:string,categories:string}`. `Presenter::brand(..., true)` adds base brand fields; these require presenter-level field enumeration before final sign-off.

### Source-verification boundaries

The controller and request rules above were checked against GitLab `main`. The exact base shapes returned by `Presenter::category`, `Presenter::brand`, `Presenter::scale`, `BrandLinkViews`, `AuditTrail`, `ImageRequest`, and `ReorderRequest` still require direct inspection; domain exception-to-HTTP mappings and staging responses have **not** been runtime-verified. Therefore these endpoints are **controller/request verified**, not yet final end-to-end contract certified.

- [CategoryAdminController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/CategoryAdminController.php)
- [BrandAdminController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/BrandAdminController.php)
- [CategoryRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Requests/CategoryRequest.php)
- [BrandRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Requests/BrandRequest.php)
- [SizeScaleRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Requests/SizeScaleRequest.php)

## Controller-verified contracts: Lookup Lists, Banners, Catalog Settings

Source basis: controllers and request classes on GitLab `main`; **source-reviewed, not staging-tested**. All paths below are relative to `/api/v1`. Every route requires `auth:sanctum` and the permission listed.

| Method | Path | Permission | Controller action |
|---|---|---|---|
| `GET` | `/admin/catalog/lists` | `lists.manage` | `lists` |
| `GET` | `/admin/catalog/lists/{key}` | `lists.manage` | `index` |
| `POST` | `/admin/catalog/lists/{key}` | `lists.manage` | `store` |
| `POST` | `/admin/catalog/lists/{key}/reorder` | `lists.manage` | `reorder` |
| `GET` | `/admin/catalog/lists/{key}/{id}` | `lists.manage` | `show` |
| `GET` | `/admin/catalog/lists/{key}/{id}/history` | `lists.manage` | `history` |
| `PUT` | `/admin/catalog/lists/{key}/{id}` | `lists.manage` | `update` |
| `POST` | `/admin/catalog/lists/{key}/{id}/activate` | `lists.manage` | `activate` |
| `POST` | `/admin/catalog/lists/{key}/{id}/deactivate` | `lists.manage` | `deactivate` |
| `GET` | `/admin/home/banners` | `banners.manage` | `index` |
| `POST` | `/admin/home/banners` | `banners.manage` | `store` |
| `POST` | `/admin/home/banners/reorder` | `banners.manage` | `reorder` |
| `GET` | `/admin/home/banners/{id}` | `banners.manage` | `show` |
| `GET` | `/admin/home/banners/{id}/history` | `banners.manage` | `history` |
| `PUT` | `/admin/home/banners/{id}` | `banners.manage` | `update` |
| `PUT` | `/admin/home/banners/{id}/image` | `banners.manage` | `image` |
| `POST` | `/admin/home/banners/{id}/activate` | `banners.manage` | `activate` |
| `POST` | `/admin/home/banners/{id}/deactivate` | `banners.manage` | `deactivate` |
| `DELETE` | `/admin/home/banners/{id}` | `banners.manage` | `destroy` |
| `GET` | `/admin/catalog/settings` | `settings.manage` | `show` |
| `PATCH` | `/admin/catalog/settings` | `settings.manage` | `update` |
| `GET` | `/admin/catalog/settings/history` | `settings.manage` | `history` |

### `GET /admin/catalog/lists`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `lists`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | none |
| Response | HTTP result and fields | data: array of {key:string,has_hex:boolean,items:int,active_items:int}; fixed lookup list names |

### `GET /admin/catalog/lists/{key}`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `index`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | key: lowercase letters or underscores |
| Response | HTTP result and fields | data: array of lookup item + products_count:int (all statuses, inactive included); ordered sort,id |

### `POST /admin/catalog/lists/{key}`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `store`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | label: localized object required, max 120 per value; hex?: string max 7; sort?: integer >=0 |
| Response | HTTP result and fields | 201 data: Presenter::lookupItem(admin=true) |

### `POST /admin/catalog/lists/{key}/reorder`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `reorder`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | ids: required nonempty distinct positive integer list, max 500 |
| Response | HTTP result and fields | 204 No Content |

### `GET /admin/catalog/lists/{key}/{id}`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `show`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | id: positive numeric route parameter |
| Response | HTTP result and fields | data: lookup item plus products_count:int, products_by_status:object, created_at, updated_at, links.history |

### `GET /admin/catalog/lists/{key}/{id}/history`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `history`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | per_page?: integer 1..100 (default 25) |
| Response | HTTP result and fields | paginated AuditTrail response for catalog_lookup_item |

### `PUT /admin/catalog/lists/{key}/{id}`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `update`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | label: localized object required; hex?: string max 7; sort?: integer >=0 |
| Response | HTTP result and fields | 200 data: Presenter::lookupItem(admin=true) |

### `POST /admin/catalog/lists/{key}/{id}/activate`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `activate`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | no JSON body |
| Response | HTTP result and fields | 200 data: Presenter::lookupItem(admin=true) |

### `POST /admin/catalog/lists/{key}/{id}/deactivate`

**Authorization:** Sanctum + `lists.manage`. **Controller:** `deactivate`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | no JSON body |
| Response | HTTP result and fields | 200 data: Presenter::lookupItem(admin=true) |

### `GET /admin/home/banners`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `index`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | filter[state]?: comma-separated live,scheduled,expired,inactive; filter[active]?: boolean |
| Response | HTTP result and fields | data: banner[]; meta:{total:int,counts:{live:int,scheduled:int,expired:int,inactive:int}}; no pagination |

### `POST /admin/home/banners`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `store`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | title: localized object required max120; target:{type:category|brand|url,id?:int,url?:string}; optional subtitle,eyebrow,cta_label,theme,starts_at,ends_at,sort,image |
| Response | HTTP result and fields | 201 data: Presenter::banner(admin=true) |

### `POST /admin/home/banners/reorder`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `reorder`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | ids: required nonempty distinct positive integer list max500 |
| Response | HTTP result and fields | 204 No Content |

### `GET /admin/home/banners/{id}`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `show`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | id: numeric |
| Response | HTTP result and fields | 200 data: Presenter::banner(admin=true) |

### `GET /admin/home/banners/{id}/history`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `history`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | per_page?: integer 1..100 (default25) |
| Response | HTTP result and fields | paginated AuditTrail; history remains accessible after banner deletion if audit exists |

### `PUT /admin/home/banners/{id}`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `update`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | same BannerRequest as create; sort REQUIRED integer >=0 on PUT |
| Response | HTTP result and fields | 200 data: Presenter::banner(admin=true) |

### `PUT /admin/home/banners/{id}/image`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `image`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | image reference from ImageRequest (see source; not yet enumerated) |
| Response | HTTP result and fields | 200 data: Presenter::banner(admin=true) |

### `POST /admin/home/banners/{id}/activate`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `activate`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | no JSON body |
| Response | HTTP result and fields | 200 data: Presenter::banner(admin=true) |

### `POST /admin/home/banners/{id}/deactivate`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `deactivate`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | no JSON body |
| Response | HTTP result and fields | 200 data: Presenter::banner(admin=true) |

### `DELETE /admin/home/banners/{id}`

**Authorization:** Sanctum + `banners.manage`. **Controller:** `destroy`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | no JSON body |
| Response | HTTP result and fields | 204 No Content |

### `GET /admin/catalog/settings`

**Authorization:** Sanctum + `settings.manage`. **Controller:** `show`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | none |
| Response | HTTP result and fields | 200 data: CatalogSettings::toArray() |

### `PATCH /admin/catalog/settings`

**Authorization:** Sanctum + `settings.manage`. **Controller:** `update`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | max_category_depth?: integer 1..5; brands_unlinked_visible?: boolean |
| Response | HTTP result and fields | 200 data: settings fields plus changed:boolean and changes:array; 422 category_depth_in_use when depth below existing tree |

### `GET /admin/catalog/settings/history`

**Authorization:** Sanctum + `settings.manage`. **Controller:** `history`.

| Direction | Field / contract | Type and rules |
|---|---|---|
| Request | Parameters/body | history query contract via SettingsHistory (requires presenter inspection) |
| Response | HTTP result and fields | SettingsHistory paginated response |

### Shared validation and integration details

**Localized fields:** `label`, `title`, `subtitle`, `eyebrow`, and `cta_label` are localized dictionaries, not scalar labels. The default language is required for required localized values; optional localized values may be omitted. `BannerRequest` limits: `title` 120, `subtitle` 200, `eyebrow` 120, `cta_label` 40 characters. `target.type` is `category`, `brand`, or `url`; `target.id` is required except for URL targets, and `target.url` is required for URL targets (max 2048). `theme` is `light` or `dark`.

**Banner scheduling:** `starts_at` and `ends_at` are nullable dates. Bare dates/times are interpreted in UTC; explicit offsets are converted to UTC. The server supplies `state`, `state_label`, and `shown_in_app`; clients should not recompute schedule state.

**Lookup behavior:** lookup lists are fixed; only their items are managed. `hex` is accepted as nullable string of up to seven characters by the request; color-specific semantic restrictions may be applied deeper in the domain. `products_count` counts products in all statuses.

**Settings:** `max_category_depth` cannot be reduced below the depth already used by the category tree; the API raises `category_depth_in_use`. `brands_unlinked_visible` controls whether unlinked general brands are visible to buyers.

**Reordering:** `ids` is a required list of 1–500 distinct positive integers. Both banners and lookup reorder endpoints return HTTP 204 with no response body.

**Remaining verification:** exact field-by-field shapes from `Presenter::banner`, `Presenter::lookupItem`, `AuditTrail`, `SettingsHistory`, `ImageRequest`, `CatalogSettings::toArray()`, and domain error mappings must be inspected before this section can be marked contract-complete. No staging response has been tested.

Sources: [LookupAdminController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/LookupAdminController.php), [BannerAdminController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/BannerAdminController.php), [CatalogSettingsController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Controllers/Admin/CatalogSettingsController.php), [BannerRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Requests/BannerRequest.php), [LocalizedItemRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Requests/LocalizedItemRequest.php), [ReorderRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Requests/ReorderRequest.php).

---

## Presenter-level contract verification — 2026-11-22

**Scope:** This section replaces earlier `Presenter::...` placeholders with exact fields read from the implementation on GitLab `main`. It is a **static source contract**, not a successful staging/integration test. All admin object responses from `ApiResponse::ok` are nested under `data`; list endpoints using `response()->json` have the envelopes described below. Optional fields may be null, and enabled translation locales are environment-dependent.

### Shared object schemas (field-by-field)

**`CategoryAdmin`** — `Presenter::category($row, true)`; returned by category create/show/update/activate/deactivate/image operations (show also adds its own fields).

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Category ID |
| `parent_id` | integer \| null | Parent category; null = root |
| `slug` | string | Category slug |
| `name` | object<string,string> | Full localized names, not a single localized string |
| `image_url` | string \| null | Temporary signed media URL |
| `size_requirement` | string | Category size requirement policy |
| `size_scale_id` | integer \| null | Associated scale |
| `sort` | integer | Display order |
| `name_definite` | object<string,string> \| null | Localized definite name |
| `is_active` | boolean | Activation state |
| `image_reference` | string \| null | Media reference usable for editing |
| `created_at`, `updated_at` | ISO-8601 string \| null | Timestamps |

`GET /admin/catalog/categories` returns `data: CategoryAdmin[]`, additionally `depth:int`, `visible:boolean`, `brands_count:int`, `products_count:int` per row. `GET /admin/catalog/categories/{id}` adds `brands_count:int`, `inherited_brands_count:int`, `products:{total:int,by_status:object<string,int>}`, `links:{brands:string,history:string}`.

**`SizeScaleAdmin`** — `Presenter::scale($row, true)`:

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Scale ID |
| `name` | object<string,string> | Full localized name |
| `values` | string[] | Ordered size labels |

`GET /admin/catalog/size-scales` adds `categories_count:int` per item. `GET /admin/catalog/size-scales/{id}` adds `categories_count:int`, `categories: Array<{id:int,name:object<string,string>,is_active:boolean}>`, `created_at`, `updated_at` (nullable ISO-8601), and `links.history:string`.

**`BrandAdmin`** — `Presenter::brand($row, true)`:

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Brand ID |
| `name` | string | Brand's canonical name |
| `ar_alias` | string \| null | Arabic search alias |
| `logo_url` | string \| null | Temporary signed URL |
| `sort` | integer | Display order |
| `is_active` | boolean | Activation state |
| `logo_reference` | string \| null | Media reference |
| `updated_at` | ISO-8601 string \| null | Update timestamp |

Brand list rows add `category_ids:int[]`, `categories_count:int`, `is_general:boolean`; brand detail adds `categories:CategoryBrandLink[]`, `offered_category_ids:int[]|null`, `unlinked_brands_visible:boolean`, `products:{total:int,by_status:object<string,int>}`, `created_at:string|null`, `links:{history:string,categories:string}`.

**`LookupItemAdmin`** — `Presenter::lookupItem($row, true)`:

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Item ID |
| `label` | object<string,string> | Full localized label |
| `hex` | string \| null | **Only present for `colors` list**; omit for other lists |
| `list` | string | Fixed lookup list key |
| `sort` | integer | Display order |
| `is_active` | boolean | Activation state |

Lookup item list adds `products_count:int`; detail adds `products_count:int`, `products_by_status:object<string,int>`, `created_at:string|null`, `updated_at:string|null`, `links.history:string`.

**`BannerAdmin`** — `Presenter::banner($row, true)`:

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Banner ID |
| `eyebrow`, `title`, `subtitle`, `cta_label` | object<string,string> \| null | Editable localized text maps (`title` required in request) |
| `theme` | `light` \| `dark` | Visual theme |
| `image_url` | string \| null | Signed media URL |
| `target` | `{type:"url",url:string}` \| `{type:"category"\|"brand",id:int}` | Discriminated navigation target |
| `sort` | integer | Display order |
| `is_active` | boolean | Activation state |
| `image_reference` | string \| null | Editable media reference |
| `starts_at`, `ends_at` | ISO-8601 string \| null | Schedule boundaries |
| `state` | `live` \| `scheduled` \| `expired` \| `inactive` | Server-computed schedule state |
| `state_label` | object<string,string> | Translations of state |
| `shown_in_app` | boolean | True exactly when state is `live` |
| `created_at`, `updated_at` | ISO-8601 string \| null | Timestamps |

**Banner state precedence:** inactive first; otherwise scheduled when `starts_at > now`; otherwise expired when `ends_at <= now`; otherwise live. `GET /admin/home/banners` returns `{data:BannerAdmin[],meta:{total:int,counts:{live:int,scheduled:int,expired:int,inactive:int}}}`; counts are calculated before filtering, while `total` counts filtered rows.

### Brand/category relationship contract

`GET /admin/catalog/categories/{id}/brands` and `PUT /admin/catalog/categories/{id}/brands` respond with `data`:

| Field | Type | Meaning |
|---|---|---|
| `category` | object | `{id:int,name:object<string,string>,parent_id:int|null,is_active:boolean,visible:boolean}` |
| `brand_ids` | int[] | IDs directly linked to category |
| `brands` | `LinkedBrand[]` | Directly linked brands |
| `inherited_brands` | `InheritedBrand[]` | Brands inherited from ancestors |
| `unlinked_brands_visible` | boolean | Whether general brands are offered |
| `general_brands_count` | integer | Active general brands |
| `general_brands_total` | integer | All general brands, including inactive |
| `links` | object | `{history:string}` |

`LinkedBrand` = `{id:int,name:string,ar_alias:string|null,is_active:boolean,logo_url:string|null,sort:int}`. `InheritedBrand` adds `via_category:{id:int,name:object<string,string>|null}`. **PUT** adds `became_category_specific:int[]` (brands that ceased to be general because they gained a direct link). The `categories` array in brand detail has entries `{id:int,name:object<string,string>,slug:string,parent_id:int|null,parent:{id:int,name:object<string,string>,is_active:boolean}|null,is_active:boolean,visible:boolean,sub_categories_inherit:boolean}`.

### History and settings contracts

**AuditTrail** (`.../{id}/history` for products, categories, brands, size scales, lookups and banners) returns `{data:AuditRow[],links,meta}`. `AuditRow` fields:

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Audit ID |
| `event` | string \| null | Event type |
| `subject` | string | Auditable type |
| `subject_id` | integer | Audited record ID |
| `old_values`, `new_values` | object \| null | Raw audited field maps |
| `changes` | array | `{field:string,old:any|null,new:any|null}[]` |
| `actor_id` | integer \| null | Actor ID |
| `actor` | `{id:int,name:string|null}` \| null | Actor resolved from users table; missing user name is null |
| `tags` | string \| null | Audit tags |
| `at` | ISO-8601 string \| null | Audit timestamp |

`links` = `{first:string,last:string,prev:string|null,next:string|null}` and `meta` = `{current_page:int,from:int|null,last_page:int,per_page:int,to:int|null,total:int}`. History defaults to 25 rows/page; most handlers accept `per_page` 1–100 and some also accept `event` max 40 characters.

**SettingsHistory** for `GET /admin/catalog/settings/history` and `GET /admin/catalog/product-settings/history`: `data` rows are `{id:int,setting:string,old:any|null,new:any|null,actor:object|null,at:string|null}`; pagination uses the same `links`/`meta` shape. Query fields: `per_page?:int` 1–100 (default 25), `filter[setting]?:string` comma-separated names, max 500 characters; `filter[actor_id]?:int` positive; `filter[from]?:date`; `filter[to]?:date`. Date bounds are inclusive calendar days. The filter object rejects unexpected keys.

**Catalog settings object** from `CatalogSettings::toArray()` is `{max_category_depth:int,brands_unlinked_visible:boolean}`. `PATCH /admin/catalog/settings` returns these keys plus `changed:boolean` and `changes:array` (each change is `{setting:string,old:any|null,new:any|null}`). `max_category_depth` must be 1–5 and cannot be lower than the existing tree depth; `brands_unlinked_visible` is boolean.

### Image replacement and reordering

- `PUT .../image` and `PUT .../logo` use `ImageRequest`: request JSON `{ "reference": "med_..." }` or `{ "reference": null }` to remove; **`reference` must be present**, nullable string max 40. This request class does not itself impose a `med_` regex; media/domain validation may apply later.
- `PUT .../reorder`: JSON `{ "ids": [3,1,2] }`, required nonempty list 1–500, distinct positive integers; categories additionally support optional `parent_id:int|null`. Response is **204 No Content**, do not parse JSON.
- Product images in `ProductRequest` use a different, stricter rule: each `images.*` must match `^med_[a-f0-9]{32}$`.

### Source and sign-off notes

Verified against:

- [Catalog Presenter](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenter.php)
- [BrandLinkViews](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenters/BrandLinkViews.php)
- [AuditTrail](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenters/AuditTrail.php)
- [SettingsHistory](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenters/SettingsHistory.php)
- [ImageRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Requests/ImageRequest.php)
- [CatalogSettings](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Infrastructure/Settings/CatalogSettings.php)

**Source-verified:** `ActorNames::actor`, `SettingRow::auditChanges`, and Core exception-to-HTTP mapping. **Not staging-tested:** live payloads, authorization, and operational edge cases.


## Final source verification — actor, settings audit and error envelope

### Actor and settings change shapes

`actor` in audit and settings-history responses is `null` if there is no actor ID; otherwise `{ "id": integer, "name": string|null }`. A deleted or unresolvable account still has its ID and `name: null`. Actor names are batch-fetched.

`PATCH /admin/catalog/settings` and `PATCH /admin/catalog/product-settings` include `changed: boolean` and `changes: [{"setting":string,"old":any|null,"new":any|null}]` inside the `data` object. `changed` is false and `changes` is empty when the saved values are unchanged. Each changed setting produces an audit event if its settings row exists.

### Exact shared success/error wrappers

- `ApiResponse::ok(value)` → HTTP 200 `{ "data": value }`. `ApiResponse::created(value)` → HTTP 201 `{ "data": value }`. `ApiResponse::noContent()` → HTTP 204 with no response body.
- Paginated admin lists and audit histories explicitly return top-level `{ "data": [...], "links": {...}, "meta": {...} }`; do **not** add a second `data` wrapper.
- Errors return `{ "error": { "code": string, "message": string, "request_id": string|null, "details"?: object } }`. The optional `details` is present for validation errors and throttling.

| HTTP | Error code | When |
|---|---|---|
| 422 | `validation_failed` | Laravel request validation; `details` maps fields to arrays of messages |
| 401 | `unauthenticated` | Missing/invalid authentication |
| 403 | `forbidden` | Permission denied |
| 404 | `category_not_found`, `size_scale_not_found`, `brand_not_found`, `lookup_list_not_found`, `lookup_item_not_found`, `banner_not_found` | Catalog missing-resource domain exceptions |
| 422 | `invalid_localized_text`, `invalid_slug`, `invalid_size_policy`, `invalid_size_values`, `invalid_brand_name` | Catalog invalid value/domain rule |
| 422 | `brand_category_not_found`, `brand_category_inactive`, `category_brand_not_found`, `category_brand_inactive` | Invalid brand/category links |
| 422 | `invalid_hex_color`, `color_hex_required`, `hex_not_allowed`, `invalid_sort` | Lookup/sorting validation |
| 422 | `invalid_banner_window`, `invalid_banner_target`, `invalid_banner_theme` | Banner validation/domain rule |
| 422 | `invalid_reorder`, `product_images_range_invalid`, `category_depth_in_use` | Ordering/settings domain rule |
| 429 | `too_many_attempts` | Rate limiting; `details.retry_after` seconds |
| 500 | `server_error` | Unexpected exception in production |

The table lists **possible** domain codes, not a guarantee every code can arise on every endpoint. Some domain exceptions also carry `reason`/`params` internally; the shared error envelope does not automatically serialize these fields into `details`. Do not assume those fields appear in the HTTP JSON response.

### Source references

- [ActorNames](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Interfaces/Http/Presenters/ActorNames.php)
- [SettingRow](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Infrastructure/Settings/SettingRow.php)
- [InvalidCatalogValue](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Domain/Exception/InvalidCatalogValue.php)
- [CatalogEntryNotFound](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Catalog/Domain/Exception/CatalogEntryNotFound.php)
- [ApiExceptionRenderer](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/Interfaces/Http/ApiExceptionRenderer.php)
- [ApiResponse](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/Interfaces/Http/Responses/ApiResponse.php)

**Sign-off:** Source contract verification completed for these shared pieces. Staging execution is outstanding and must not be represented as passed.
