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

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

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

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

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

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

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

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

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

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

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

curl -X GET "https://jethings-backend.fly.dev/stores/my" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Search stores:

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

Filter by status:

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

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

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

Search stores:

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

Filter by user:

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

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

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

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

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

{
  "message": "Error description",
  "statusCode": 400
}

Business Logic

Store Creation Flow

User creates a store with name, description, and optional icon
Store is created with status: "pending" and isActive: true
Store names can be duplicated (no uniqueness constraint)
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

​Stores Management API

​Conventions

​Create Store

​Request Body

​Success Response

​Possible Errors

​Example Request

​Update Store (Admin Only)

​Path Parameters

​Request Body

​Success Response

​Possible Errors

​Example Request

​Update Store (User)

​Path Parameters

​Request Body

​Success Response

​Possible Errors

​Example Request

​Get User’s Stores

​Query Parameters

​Success Response

​Example Requests

​Get All Stores (Admin Only)

​Query Parameters

​Success Response

​Example Requests

​Get Store by ID

​Path Parameters

​Success Response

​Possible Errors

​Example Request

​Delete Store (Admin Only)

​Path Parameters

​Success Response

​Possible Errors

​Example Request

​Store Status Values

​Error Responses

​Common Error Codes

​Error Response Format

​Business Logic

​Store Creation Flow

​Store Update Permissions

​Store Deletion

Stores Management API

Conventions

Create Store

Request Body

Success Response

Possible Errors

Example Request

Update Store (Admin Only)

Path Parameters

Request Body

Success Response

Possible Errors

Example Request

Update Store (User)

Path Parameters

Request Body

Success Response

Possible Errors

Example Request

Get User’s Stores

Query Parameters

Success Response

Example Requests

Get All Stores (Admin Only)

Query Parameters

Success Response

Example Requests

Get Store by ID

Path Parameters

Success Response

Possible Errors

Example Request

Delete Store (Admin Only)

Path Parameters

Success Response

Possible Errors

Example Request

Store Status Values

Error Responses

Common Error Codes

Error Response Format

Business Logic

Store Creation Flow

Store Update Permissions

Store Deletion