Support Cases API

REST API endpoints for creating and managing merchant support cases.

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

{
  "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`)

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)

{
  "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).

Response

{
  "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"
    }
  ]
}

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`

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

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`)

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)

{
  "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"
}

PreviousLegal PagesAPI Reference NextFeedback SessionsAPI Reference