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

# Support API — Flutter (source-reviewed contracts)

**Source:** [Routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Support/Routes/api.php), [controllers and request classes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Support/Interfaces/Http/Controllers/SupportController.php). **Base URL:** `/api/v1`.

**Status:** 9 route operations covered. JSON values below are **illustrative**, not captured runtime responses. Some admin presenter-dependent fields and enum values are explicitly pending verification; do not infer omitted fields are absent. Common success is `{"data":...}`, except list endpoints which may include `links`, `meta`, etc. Errors are localized and their exact error envelopes are not asserted without inspecting middleware.

## `GET /api/v1/support/policies`

**Purpose:** Public policy list. **Access:** Authenticated (except public policies).

**Path / query:** —.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "title": "Policies",
    "rows": [
      {
        "slug": "terms",
        "title": "Terms",
        "published_at": "2026-11-20T10:00:00+00:00",
        "endpoint": "/api/v1/content/terms"
      }
    ],
    "last_updated": "2026-11-20T10:00:00+00:00",
    "last_updated_label": "20 November 2026"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; public; only published Pages appear.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/support`

**Purpose:** Support screen configuration. **Access:** Authenticated (except public policies).

**Path / query:** —.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "title": "Support",
    "faq": {
      "title": "FAQ",
      "items": [
        {
          "slug": "faq",
          "question": "How?",
          "answer": "<p>Answer</p>"
        }
      ]
    },
    "form": {
      "title": "Send",
      "topics": [
        {
          "code": "delivery",
          "name": "Delivery",
          "selected": true
        }
      ],
      "orders_endpoint": "/api/v1/support/orders",
      "message_min": 10,
      "message_max": 10000,
      "attachments_max": 5,
      "upload_endpoint": "/api/v1/media",
      "can_send": true,
      "cannot_send_reason": null
    },
    "contact": {
      "email": {
        "label": "Email",
        "value": "support@example.com"
      },
      "hours": {
        "label": "Hours",
        "value": "Daily"
      }
    },
    "my_tickets": {
      "label": "My tickets",
      "count": 1,
      "endpoint": "/api/v1/support/tickets"
    }
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; response includes additional localized form labels, placeholders, hint and text fields.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/support/topics`

**Purpose:** Available topic chips. **Access:** Authenticated (except public policies).

**Path / query:** —.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": [
    {
      "code": "delivery",
      "name": "Delivery",
      "selected": true
    }
  ]
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; active topics sorted by sort/id.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/support/orders`

**Purpose:** My order picker. **Access:** Authenticated (except public policies).

**Path / query:** q:string? max20; limit:int? 1..100 default50.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "title": "Select order",
    "selected": null,
    "options": [
      {
        "value": null,
        "label": "Not related to order",
        "role": null
      },
      {
        "value": "OUT-123",
        "label": "OUT-123 · Item",
        "role": "buyer",
        "item_name": "Item",
        "paid_at": "2026-11-20T10:00:00+00:00"
      }
    ]
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; only own orders; first option has null value.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/support/tickets`

**Purpose:** Create support ticket. **Access:** Authenticated (except public policies).

**Path / query:** —.

**Request body / validation:** topic:string required max40; order_ref:string|null max20; message:string required max20000; attachments:string[]? max domain hard limit, each max64.

**Example request body:**
```json
{
  "topic": "delivery",
  "order_ref": "OUT-123",
  "message": "Please help with my order",
  "attachments": []
}
```

**Illustrative success response:**
```json
{
  "data": {
    "message": "Ticket submitted",
    "ref": "SUP-123",
    "topic": {
      "code": "delivery",
      "name": "Delivery"
    },
    "order": null,
    "status": {
      "value": "open"
    },
    "has_new_reply": false,
    "last_message": null,
    "messages_count": 1,
    "opened_at": "2026-11-22T10:00:00+00:00",
    "last_activity_at": "2026-11-22T10:00:00+00:00",
    "closed_at": null,
    "closed_by": null,
    "messages": [
      {
        "id": 1,
        "from": "you",
        "author_label": "You",
        "body": "Please help with my order",
        "attachments": [],
        "at": "2026-11-22T10:00:00+00:00"
      }
    ],
    "actions": {
      "can_reply": true,
      "reply_reopens": false,
      "reopen_until": null,
      "can_close": true
    },
    "notice": null,
    "reply_form": {
      "placeholder": "Write a reply",
      "close_label": "Close",
      "message_min": 10,
      "message_max": 10000,
      "attachments_max": 5,
      "upload_endpoint": "/api/v1/media"
    }
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 201; Idempotency-Key supported; domain checks configured message length, topic and order ownership.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/support/tickets`

**Purpose:** My tickets. **Access:** Authenticated (except public policies).

**Path / query:** per_page:int? 1..50 default20; filter[status]:open|closed.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": [
    {
      "ref": "SUP-123",
      "topic": {
        "code": "delivery",
        "name": "Delivery"
      },
      "order": null,
      "status": {
        "value": "open"
      },
      "has_new_reply": false,
      "last_message": null,
      "messages_count": 1,
      "opened_at": "2026-11-22T10:00:00+00:00",
      "last_activity_at": "2026-11-22T10:00:00+00:00"
    }
  ],
  "empty": "No tickets",
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1
  },
  "links": {
    "next": null,
    "prev": null
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; open means status != closed; excludes internal notes.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/support/tickets/{ref}`

**Purpose:** My ticket thread. **Access:** Authenticated (except public policies).

**Path / query:** ref:path regex [A-Za-z]{3}-?[0-9]{1,12}.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "ref": "SUP-123",
    "topic": {
      "code": "delivery",
      "name": "Delivery"
    },
    "order": null,
    "status": {
      "value": "open"
    },
    "has_new_reply": false,
    "last_message": null,
    "messages_count": 1,
    "opened_at": "2026-11-22T10:00:00+00:00",
    "last_activity_at": "2026-11-22T10:00:00+00:00",
    "closed_at": null,
    "closed_by": null,
    "messages": [
      {
        "id": 1,
        "from": "you",
        "author_label": "You",
        "body": "Please help with my order",
        "attachments": [],
        "at": "2026-11-22T10:00:00+00:00"
      }
    ],
    "actions": {
      "can_reply": true,
      "reply_reopens": false,
      "reopen_until": null,
      "can_close": true
    },
    "notice": null,
    "reply_form": {
      "placeholder": "Write a reply",
      "close_label": "Close",
      "message_min": 10,
      "message_max": 10000,
      "attachments_max": 5,
      "upload_endpoint": "/api/v1/media"
    }
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; 404 for unknown/foreign ticket; notes and assignee/priority hidden.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/support/tickets/{ref}/replies`

**Purpose:** Reply to my ticket. **Access:** Authenticated (except public policies).

**Path / query:** ref:path.

**Request body / validation:** message:string required max20000; attachments:string[]? max hard limit each max64.

**Example request body:**
```json
{
  "message": "Additional details",
  "attachments": []
}
```

**Illustrative success response:**
```json
{
  "data": {
    "message_id": 2,
    "message": "Reply sent",
    "ref": "SUP-123",
    "topic": {
      "code": "delivery",
      "name": "Delivery"
    },
    "order": null,
    "status": {
      "value": "open"
    },
    "has_new_reply": false,
    "last_message": null,
    "messages_count": 1,
    "opened_at": "2026-11-22T10:00:00+00:00",
    "last_activity_at": "2026-11-22T10:00:00+00:00",
    "closed_at": null,
    "closed_by": null,
    "messages": [
      {
        "id": 1,
        "from": "you",
        "author_label": "You",
        "body": "Please help with my order",
        "attachments": [],
        "at": "2026-11-22T10:00:00+00:00"
      }
    ],
    "actions": {
      "can_reply": true,
      "reply_reopens": false,
      "reopen_until": null,
      "can_close": true
    },
    "notice": null,
    "reply_form": {
      "placeholder": "Write a reply",
      "close_label": "Close",
      "message_min": 10,
      "message_max": 10000,
      "attachments_max": 5,
      "upload_endpoint": "/api/v1/media"
    }
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 201; Idempotency-Key supported; closed tickets may reopen within configured window.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/support/tickets/{ref}/close`

**Purpose:** Close my ticket. **Access:** Authenticated (except public policies).

**Path / query:** ref:path.

**Request body / validation:** No request body.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "message": "Ticket closed",
    "ref": "SUP-123",
    "topic": {
      "code": "delivery",
      "name": "Delivery"
    },
    "order": null,
    "status": {
      "value": "open"
    },
    "has_new_reply": false,
    "last_message": null,
    "messages_count": 1,
    "opened_at": "2026-11-22T10:00:00+00:00",
    "last_activity_at": "2026-11-22T10:00:00+00:00",
    "closed_at": null,
    "closed_by": null,
    "messages": [
      {
        "id": 1,
        "from": "you",
        "author_label": "You",
        "body": "Please help with my order",
        "attachments": [],
        "at": "2026-11-22T10:00:00+00:00"
      }
    ],
    "actions": {
      "can_reply": true,
      "reply_reopens": false,
      "reopen_until": null,
      "can_close": true
    },
    "notice": null,
    "reply_form": {
      "placeholder": "Write a reply",
      "close_label": "Close",
      "message_min": 10,
      "message_max": 10000,
      "attachments_max": 5,
      "upload_endpoint": "/api/v1/media"
    }
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; repeat action may return changed=false.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.
