> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jethings.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stores api

# Stores Management API

Audience: Frontend engineers and administrators managing store data.

* Base URL: `https://jethings-backend.fly.dev`
* Content-Type: `application/json`

### Conventions

* All responses are JSON.
* Errors follow standard HTTP status codes with `{ message: string }` body.
* Unless noted, successful responses are `200 OK`.
* Admin endpoints require `admin` or `super_admin` role.
* All endpoints require authentication via Bearer token.

***

## Create Store

POST `/stores`

**Requires Authentication:** Bearer token in Authorization header

### Request Body

```json theme={null}
{
  "name": "My Store",
  "description": "A great store for selling products",
  "icon": "https://example.com/store-icon.png"
}
```

| Field         | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `name`        | string | Yes      | Store name (max 255 characters, can be duplicated) |
| `description` | string | No       | Store description (max 1000 characters)            |
| `icon`        | string | No       | Store icon URL (max 500 characters)                |

### Success Response

```json theme={null}
{
  "id": "ck_123...",
  "userId": "ck_456...",
  "name": "My Store",
  "description": "A great store for selling products",
  "icon": "https://example.com/store-icon.png",
  "status": "pending",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "deletedAt": null
}
```

### Possible Errors

* `400 Bad Request`: Invalid request data or validation errors

### Example Request

```bash theme={null}
curl -X POST "https://jethings-backend.fly.dev/stores" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "name": "My Store",
    "description": "A great store for selling products",
    "icon": "https://example.com/store-icon.png"
  }'
```

***

## Update Store (Admin Only)

PUT `/stores/:id`

**Requires Authentication:** Bearer token in Authorization header\
**Requires Role:** Admin or Super Admin

### Path Parameters

* `id` (string): Store ID (UUID format)

### Request Body

```json theme={null}
{
  "name": "Updated Store Name",
  "description": "Updated store description",
  "icon": "https://example.com/new-icon.png",
  "status": "accepted",
  "isActive": true
}
```

| Field         | Type    | Required | Description                                        |
| ------------- | ------- | -------- | -------------------------------------------------- |
| `name`        | string  | No       | Store name (max 255 characters, can be duplicated) |
| `description` | string  | No       | Store description (max 1000 characters)            |
| `icon`        | string  | No       | Store icon URL (max 500 characters)                |
| `status`      | string  | No       | Store status: 'pending', 'rejected', 'accepted'    |
| `isActive`    | boolean | No       | Store active status                                |

### Success Response

```json theme={null}
{
  "id": "ck_123...",
  "userId": "ck_456...",
  "name": "Updated Store Name",
  "description": "Updated store description",
  "icon": "https://example.com/new-icon.png",
  "status": "accepted",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T11:00:00.000Z",
  "deletedAt": null
}
```

### Possible Errors

* `404 Not Found`: `{ "message": "Store not found" }`

### Example Request

```bash theme={null}
curl -X PUT "https://jethings-backend.fly.dev/stores/ck_123..." \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "name": "Updated Store Name",
    "status": "accepted",
    "isActive": true
  }'
```

***

## Update Store (User)

PUT `/stores/:id/user`

**Requires Authentication:** Bearer token in Authorization header

### Path Parameters

* `id` (string): Store ID (UUID format)

### Request Body

```json theme={null}
{
  "name": "My Updated Store",
  "description": "Updated description",
  "icon": "https://example.com/new-icon.png"
}
```

| Field         | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `name`        | string | No       | Store name (max 255 characters, can be duplicated) |
| `description` | string | No       | Store description (max 1000 characters)            |
| `icon`        | string | No       | Store icon URL (max 500 characters)                |

**Note:** Users can only update their own stores and cannot change status or isActive fields.

### Success Response

```json theme={null}
{
  "id": "ck_123...",
  "userId": "ck_456...",
  "name": "My Updated Store",
  "description": "Updated description",
  "icon": "https://example.com/new-icon.png",
  "status": "pending",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T11:00:00.000Z",
  "deletedAt": null
}
```

### Possible Errors

* `404 Not Found`: `{ "message": "Store not found or you do not have permission to update it" }`

### Example Request

```bash theme={null}
curl -X PUT "https://jethings-backend.fly.dev/stores/ck_123.../user" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "name": "My Updated Store",
    "description": "Updated description"
  }'
```

***

## Get User's Stores

GET `/stores/my`

**Requires Authentication:** Bearer token in Authorization header

### Query Parameters

| Parameter   | Type      | Required | Description                                         |
| ----------- | --------- | -------- | --------------------------------------------------- |
| `search`    | string    | No       | Search across name and description                  |
| `name`      | string    | No       | Filter by store name (partial match)                |
| `status`    | string\[] | No       | Filter by status: 'pending', 'rejected', 'accepted' |
| `isActive`  | boolean   | No       | Filter by active status                             |
| `page`      | number    | No       | Page number (default: 1)                            |
| `limit`     | number    | No       | Items per page (default: 10, max: 100)              |
| `sortBy`    | string    | No       | Sort field (default: 'createdAt')                   |
| `sortOrder` | string    | No       | Sort order: 'asc' or 'desc' (default: 'desc')       |

### Success Response

```json theme={null}
{
  "stores": [
    {
      "id": "ck_123...",
      "userId": "ck_456...",
      "name": "My Store",
      "description": "A great store for selling products",
      "icon": "https://example.com/store-icon.png",
      "status": "pending",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "deletedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

### Example Requests

Get all user's stores:

```bash theme={null}
curl -X GET "https://jethings-backend.fly.dev/stores/my" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Search stores:

```bash theme={null}
curl -X GET "https://jethings-backend.fly.dev/stores/my?search=electronics&status[]=accepted" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Filter by status:

```bash theme={null}
curl -X GET "https://jethings-backend.fly.dev/stores/my?status[]=pending&status[]=accepted" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## Get All Stores (Admin Only)

GET `/stores`

**Requires Authentication:** Bearer token in Authorization header\
**Requires Role:** Admin or Super Admin

### Query Parameters

| Parameter   | Type      | Required | Description                                         |
| ----------- | --------- | -------- | --------------------------------------------------- |
| `search`    | string    | No       | Search across name and description                  |
| `name`      | string    | No       | Filter by store name (partial match)                |
| `userId`    | string    | No       | Filter by user ID                                   |
| `status`    | string\[] | No       | Filter by status: 'pending', 'rejected', 'accepted' |
| `isActive`  | boolean   | No       | Filter by active status                             |
| `page`      | number    | No       | Page number (default: 1)                            |
| `limit`     | number    | No       | Items per page (default: 10, max: 100)              |
| `sortBy`    | string    | No       | Sort field (default: 'createdAt')                   |
| `sortOrder` | string    | No       | Sort order: 'asc' or 'desc' (default: 'desc')       |

### Success Response

```json theme={null}
{
  "stores": [
    {
      "id": "ck_123...",
      "userId": "ck_456...",
      "name": "Electronics Store",
      "description": "Best electronics in town",
      "icon": "https://example.com/electronics-icon.png",
      "status": "accepted",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T11:00:00.000Z",
      "deletedAt": null
    },
    {
      "id": "ck_789...",
      "userId": "ck_101...",
      "name": "Fashion Store",
      "description": "Trendy fashion items",
      "icon": "https://example.com/fashion-icon.png",
      "status": "pending",
      "isActive": true,
      "createdAt": "2024-01-14T09:15:00.000Z",
      "updatedAt": "2024-01-14T09:15:00.000Z",
      "deletedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}
```

### Example Requests

Get all stores with pagination:

```bash theme={null}
curl -X GET "https://jethings-backend.fly.dev/stores?page=1&limit=10" \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

Search stores:

```bash theme={null}
curl -X GET "https://jethings-backend.fly.dev/stores?search=electronics&status[]=accepted" \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

Filter by user:

```bash theme={null}
curl -X GET "https://jethings-backend.fly.dev/stores?userId=ck_456..." \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

***

## Get Store by ID

GET `/stores/:id`

**Requires Authentication:** Bearer token in Authorization header

### Path Parameters

* `id` (string): Store ID (UUID format)

### Success Response

```json theme={null}
{
  "id": "ck_123...",
  "userId": "ck_456...",
  "name": "My Store",
  "description": "A great store for selling products",
  "icon": "https://example.com/store-icon.png",
  "status": "pending",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "deletedAt": null
}
```

### Possible Errors

* `404 Not Found`: `{ "message": "Store not found" }`

### Example Request

```bash theme={null}
curl -X GET "https://jethings-backend.fly.dev/stores/ck_123..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## Delete Store (Admin Only)

DELETE `/stores/:id`

**Requires Authentication:** Bearer token in Authorization header\
**Requires Role:** Admin or Super Admin

### Path Parameters

* `id` (string): Store ID (UUID format)

### Success Response

```json theme={null}
{
  "message": "Store deleted successfully"
}
```

### Possible Errors

* `404 Not Found`: `{ "message": "Store not found" }`

**Note:** This performs a soft delete by setting the `deletedAt` timestamp. The store data is preserved but hidden from normal queries.

### Example Request

```bash theme={null}
curl -X DELETE "https://jethings-backend.fly.dev/stores/ck_123..." \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

***

## Store Status Values

The store status field can have the following values:

| Status     | Description                                |
| ---------- | ------------------------------------------ |
| `pending`  | Store is awaiting admin approval (default) |
| `rejected` | Store has been rejected by admin           |
| `accepted` | Store has been approved by admin           |

***

## Error Responses

### Common Error Codes

* `400 Bad Request`: Invalid request data or validation errors
* `401 Unauthorized`: Missing or invalid authentication token
* `403 Forbidden`: Insufficient permissions (not admin for admin-only endpoints)
* `404 Not Found`: Resource not found
* `500 Internal Server Error`: Server error

### Error Response Format

```json theme={null}
{
  "message": "Error description",
  "statusCode": 400
}
```

***

## Business Logic

### Store Creation Flow

1. User creates a store with name, description, and optional icon
2. Store is created with `status: "pending"` and `isActive: true`
3. Store names can be duplicated (no uniqueness constraint)
4. Admin can later approve/reject the store

### Store Update Permissions

* **Users**: Can update name, description, and icon of their own stores
* **Admins**: Can update any field including status and isActive
* **Status Changes**: Only admins can change store status (pending/rejected/accepted)

### Store Deletion

* Only admins can delete stores
* Deletion is soft (sets deletedAt timestamp)
* Deleted stores are hidden from normal queries but data is preserved