Support cases let merchants submit and track support requests. Each case has a subject, category, severity, and a thread of messages. Cases are scoped to the authenticated store.

## List Support Cases

```
GET /api/v1/support-cases
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 10 | Cases per page (1-100) |
| `offset` | `number` | 0 | Cases to skip |
| `query` | `string` | – | Search by subject or case number |
| `status` | `string` | – | Filter by status: `open`, `answered`, `closed`, or `all` |
| `severity` | `string` | – | Filter by severity: `critical`, `high`, `normal`, `low`, or `all` |

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "number": 42,
      "subject": "Cannot process refund for order #1042",
      "category": "orders_payments",
      "severity": "high",
      "status": "open",
      "createdAt": "2024-06-15T10:30:00.000Z",
      "lastActivityAt": "2024-06-15T14:22:00.000Z",
      "closedAt": null
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 10
  }
}
```

---

## Create Support Case

```
POST /api/v1/support-cases
```

Opens a new support case. If `subject` is omitted, one is generated automatically from the body text.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `body` | `string` | Yes | Description of the issue (10-10,000 characters) |
| `subject` | `string` | No | Case title (3-200 characters). Auto-generated from body if omitted |
| `category` | `string` | No | `orders_payments`, `products_catalog`, `domains_setup`, `billing_plans`, `store_builder`, or `other` (default `other`) |
| `severity` | `string` | No | `critical`, `high`, `normal`, or `low` (default `normal`) |
| `author` | `string` | No | Author label shown in the thread (1-120 characters, default `API`) |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Order #1042 was marked as refunded but the customer did not receive the funds. Stripe dashboard shows the refund as pending for over 48 hours.",
    "category": "orders_payments",
    "severity": "high"
  }' \
  https://your-store.yns.store/api/v1/support-cases
```

### Response (201)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "number": 42,
  "subject": "Refund pending for order #1042",
  "category": "orders_payments",
  "severity": "high",
  "status": "open",
  "createdAt": "2024-06-15T10:30:00.000Z",
  "lastActivityAt": "2024-06-15T10:30:00.000Z",
  "closedAt": null
}
```

---

## Get Support Case

```
GET /api/v1/support-cases/:idOrNumber
```

Returns a single support case with its full message thread. The path parameter accepts a UUID or a case number (e.g. `42`, `000042`, or `#000042`).

### Message `authorKind` values

| Value | Description |
|-------|-------------|
| `merchant` | Message from the merchant (via API or dashboard) |
| `support` | Reply from YNS support |
| `system` | Informational marker generated by the platform (e.g. when a message is moved to a new case via automatic topic splitting) |

### Response

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "number": 42,
  "subject": "Cannot process refund for order #1042",
  "category": "orders_payments",
  "severity": "high",
  "status": "answered",
  "createdAt": "2024-06-15T10:30:00.000Z",
  "lastActivityAt": "2024-06-15T14:22:00.000Z",
  "closedAt": null,
  "messages": [
    {
      "id": "0191abc0-2222-7def-8000-000000000010",
      "authorKind": "merchant",
      "authorLabel": "API",
      "body": "Order #1042 was marked as refunded but the customer did not receive the funds.",
      "attachments": [],
      "createdAt": "2024-06-15T10:30:00.000Z"
    },
    {
      "id": "0191abc0-3333-7def-8000-000000000020",
      "authorKind": "support",
      "authorLabel": "YNS Support",
      "body": "We've escalated this with Stripe. The refund should clear within 24 hours.",
      "attachments": [],
      "createdAt": "2024-06-15T14:22:00.000Z"
    },
    {
      "id": "0191abc0-4444-7def-8000-000000000040",
      "authorKind": "system",
      "authorLabel": "YNS",
      "body": "Moved to a new discussion: #000043 – Custom domain stopped resolving",
      "attachments": [],
      "createdAt": "2024-06-15T15:00:00.000Z"
    }
  ]
}
```

---

## Update Support Case

```
PATCH /api/v1/support-cases/:idOrNumber
```

Reopens or closes a support case. The `answered` status is set by YNS support only and cannot be set via this endpoint.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | `string` | Yes | `open` or `closed` |

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed"}' \
  https://your-store.yns.store/api/v1/support-cases/42
```

### Response (200)

Returns the updated support case (same shape as the case object in [List Support Cases](#list-support-cases)).

---

## Add Reply

```
POST /api/v1/support-cases/:idOrNumber/messages
```

Adds a merchant reply to the case thread. Replying to a closed or answered case automatically reopens it.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `body` | `string` | Yes | Reply text (1-10,000 characters) |
| `author` | `string` | No | Author label (1-120 characters, default `API`) |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "Thanks – the customer confirmed the refund arrived."}' \
  https://your-store.yns.store/api/v1/support-cases/42/messages
```

### Response (201)

```json
{
  "message": {
    "id": "0191abc0-4444-7def-8000-000000000030",
    "authorKind": "merchant",
    "authorLabel": "API",
    "body": "Thanks – the customer confirmed the refund arrived.",
    "attachments": [],
    "createdAt": "2024-06-16T09:15:00.000Z"
  },
  "status": "open"
}
```